@mukae/client 0.0.0-stage → 0.1.0-beta.0

package/dist/choose-connect-action.d.ts

@@ -0,0 +1,20 @@
+import type { GatewayStatus } from "@mukae/contract";
+export type StatusObservation = GatewayStatus | "unreachable" | "rejected";
+export type ConnectAction = {
+    type: "wait";
+} | {
+    type: "open-socket";
+} | {
+    type: "unconfigured";
+} | {
+    type: "cancelled";
+} | {
+    type: "documentation";
+    url: string;
+};
+export declare function chooseConnectAction(input: {
+    observation: StatusObservation;
+    elapsedMs: number;
+    readyTimeoutMs: number;
+    documentationUrl: string;
+}): ConnectAction;

package/dist/choose-connect-action.js

@@ -0,0 +1,15 @@
+export function chooseConnectAction(input) {
+    if (input.observation === "waiting")
+        return { type: "open-socket" };
+    if (input.observation === "unconfigured")
+        return { type: "unconfigured" };
+    if (input.observation === "cancelled")
+        return { type: "cancelled" };
+    if (input.observation === "choosing")
+        return { type: "wait" };
+    if (input.observation === "rejected" || input.elapsedMs >= input.readyTimeoutMs) {
+        return { type: "documentation", url: input.documentationUrl };
+    }
+    return { type: "wait" };
+}
+//# sourceMappingURL=choose-connect-action.js.map

package/dist/choose-connect-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"choose-connect-action.js","sourceRoot":"","sources":["../src/choose-connect-action.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,mBAAmB,CAAC,KAKnC;IACC,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IACpE,IAAI,KAAK,CAAC,WAAW,KAAK,cAAc;QAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAC1E,IAAI,KAAK,CAAC,WAAW,KAAK,WAAW;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACpE,IAAI,KAAK,CAAC,WAAW,KAAK,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC9D,IAAI,KAAK,CAAC,WAAW,KAAK,UAAU,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QAChF,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,KAAK,CAAC,gBAAgB,EAAE,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC"}

package/dist/connect.d.ts

@@ -0,0 +1,32 @@
+import { type StatusObservation } from "./choose-connect-action.js";
+export type ConnectOutcome = {
+    connected: true;
+    url: string;
+} | {
+    connected: false;
+    reason: "unconfigured" | "cancelled" | "not_ready" | "no_free_port";
+};
+export declare const defaultReadyTimeoutMs = 60000;
+/** Published setup page. A web app passes this as `documentationUrl`. */
+export declare const explainPageUrl = "https://lulu0119.github.io/mukae/explain/";
+export type ConnectDependencies = {
+    documentationUrl: string;
+    agentType: string;
+    port: number;
+    readyTimeoutMs: number;
+    origin: string;
+    createNonce: () => string;
+    openLaunchUrl: (url: string) => void;
+    readStatus: (port: number) => Promise<StatusObservation>;
+    goToDocumentation: (url: string) => void;
+    sleep: (milliseconds: number) => Promise<void>;
+    now: () => number;
+};
+/** Opens one more connection on a free port, so existing connections stay open. */
+export declare function connectLocalGateway(options: {
+    documentationUrl: string;
+    agentType: string;
+    readyTimeoutMs?: number;
+}): Promise<ConnectOutcome>;
+export declare function runConnect(input: ConnectDependencies): Promise<ConnectOutcome>;
+export declare function readGatewayStatus(port: number): Promise<StatusObservation>;

package/dist/connect.js

@@ -0,0 +1,77 @@
+import { buildLaunchUrl, buildStatusUrl, buildWebSocketUrl, gatewayPortCandidates, parseStatusBody, } from "@mukae/contract";
+import { chooseConnectAction } from "./choose-connect-action.js";
+import { pickFreeGatewayPort } from "./pick-port.js";
+export const defaultReadyTimeoutMs = 60_000;
+/** Published setup page. A web app passes this as `documentationUrl`. */
+export const explainPageUrl = "https://lulu0119.github.io/mukae/explain/";
+const pollIntervalMs = 250;
+/** Opens one more connection on a free port, so existing connections stay open. */
+export async function connectLocalGateway(options) {
+    const port = await pickFreeGatewayPort({ candidates: gatewayPortCandidates, readStatus: readGatewayStatus });
+    if (port === undefined)
+        return { connected: false, reason: "no_free_port" };
+    return runConnect({
+        documentationUrl: options.documentationUrl,
+        agentType: options.agentType,
+        port,
+        readyTimeoutMs: options.readyTimeoutMs ?? defaultReadyTimeoutMs,
+        origin: window.location.origin,
+        createNonce: () => crypto.randomUUID(),
+        openLaunchUrl: openCustomScheme,
+        readStatus: readGatewayStatus,
+        goToDocumentation: (url) => window.location.assign(url),
+        sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+        now: () => Date.now(),
+    });
+}
+export async function runConnect(input) {
+    const nonce = input.createNonce();
+    input.openLaunchUrl(buildLaunchUrl({ nonce, origin: input.origin, agentType: input.agentType, port: input.port }));
+    const started = input.now();
+    while (true) {
+        const observation = await input.readStatus(input.port);
+        const elapsedMs = input.now() - started;
+        const action = chooseConnectAction({
+            observation,
+            elapsedMs,
+            readyTimeoutMs: input.readyTimeoutMs,
+            documentationUrl: input.documentationUrl,
+        });
+        if (action.type === "wait") {
+            await input.sleep(pollIntervalMs);
+            continue;
+        }
+        if (action.type === "unconfigured")
+            return { connected: false, reason: "unconfigured" };
+        if (action.type === "cancelled")
+            return { connected: false, reason: "cancelled" };
+        if (action.type === "documentation") {
+            input.goToDocumentation(action.url);
+            return { connected: false, reason: "not_ready" };
+        }
+        return { connected: true, url: buildWebSocketUrl({ port: input.port, nonce }) };
+    }
+}
+export async function readGatewayStatus(port) {
+    try {
+        const response = await fetch(buildStatusUrl(port), { targetAddressSpace: "loopback" });
+        if (response.status === 403)
+            return "rejected";
+        if (!response.ok)
+            return "unreachable";
+        const status = parseStatusBody(await response.json());
+        return status ?? "unreachable";
+    }
+    catch {
+        return "unreachable";
+    }
+}
+function openCustomScheme(url) {
+    const link = document.createElement("a");
+    link.href = url;
+    link.hidden = true;
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+}
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { connectLocalGateway, explainPageUrl, type ConnectOutcome } from "./connect.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { connectLocalGateway, explainPageUrl } from "./connect.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAuB,MAAM,cAAc,CAAC"}

package/dist/pick-port.d.ts

@@ -0,0 +1,6 @@
+import type { StatusObservation } from "./choose-connect-action.js";
+/** The first candidate port with no gateway answering on it. */
+export declare function pickFreeGatewayPort(input: {
+    candidates: readonly number[];
+    readStatus: (port: number) => Promise<StatusObservation>;
+}): Promise<number | undefined>;

package/dist/pick-port.js

@@ -0,0 +1,9 @@
+/** The first candidate port with no gateway answering on it. */
+export async function pickFreeGatewayPort(input) {
+    for (const port of input.candidates) {
+        if ((await input.readStatus(port)) === "unreachable")
+            return port;
+    }
+    return undefined;
+}
+//# sourceMappingURL=pick-port.js.map

package/dist/pick-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick-port.js","sourceRoot":"","sources":["../src/pick-port.ts"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,KAGzC;IACC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACpC,IAAI,CAAC,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC;IACpE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@mukae/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.0",
+  "description": "Browser helper that opens the local mukae gateway from a click.",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lulu0119/mukae.git",
+    "directory": "packages/client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@mukae/contract": "0.1.0-beta.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && printf '%s\n' '*.test.js' '*.test.js.map' '*.test.d.ts' '*.test.d.ts.map' '*.tsbuildinfo' > dist/.npmignore",
+    "test": "tsc -p tsconfig.json && node --test dist/choose-connect-action.test.js dist/connect.test.js dist/pick-port.test.js"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.