@xfey/tutti 0.1.0

package/dist/server-shell/cli/host-lifecycle.js

@@ -0,0 +1,298 @@
+import { resolve } from "node:path";
+import { redactText } from "@tutti/shared/utils";
+import { connectRelayHostTunnel, RelayHostControlClientError, refreshRelayJoinToken as refreshRelayJoinTokenWithRelay, registerRelayHostConnection as registerRelayHostConnectionWithRelay, } from "@tutti/relay-client";
+import { createHostServer } from "../http/create-server.js";
+import { createHostProjectApiTunnelRequestHandler, createHostProjectApiTunnelStreamRequestHandler, } from "../http/host-tunnel.js";
+import { LaunchError } from "./errors.js";
+import { TUTTI_MAINLINE_BRANCH } from "./git-bootstrap.js";
+import { relayStateFromLaunchStatus, relayStatusFromLocalStatus } from "./host-relay-status.js";
+import { createRuntimeEndpointProbe, readExistingHostLaunchStatus, requestExistingHostShutdown, } from "./host-runtime-endpoint.js";
+import { HOST_SERVER_VERSION, startForegroundHostServer, } from "./host-server-runtime.js";
+import { deleteMachineRuntimeEndpoint, readHostRegistrationSecret, readMachineProjectBinding, readMachineRuntimeEndpoint, } from "./machine-local.js";
+import { prepareLaunchProject, resolveLaunchLocalContext, } from "./launch.js";
+import { registerHostWithRelay, relayErrorToLaunchError, } from "./relay-registration.js";
+export { createRuntimeEndpointProbe } from "./host-runtime-endpoint.js";
+const DEFAULT_SHUTDOWN_WAIT_MS = 2_000;
+function endpointWithoutToken(endpoint) {
+    return {
+        project_id: endpoint.project_id,
+        pid: endpoint.pid,
+        base_url: endpoint.base_url,
+        workspace_root: endpoint.workspace_root,
+        updated_at: endpoint.updated_at,
+    };
+}
+function setupUrl(endpoint) {
+    const url = new URL("/setup", endpoint.base_url);
+    url.searchParams.set("token", endpoint.token);
+    return url.toString();
+}
+async function requireTakeoverConfirmation(options) {
+    if (options.launchOptions.yes === true) {
+        return;
+    }
+    const accepted = (await options.launchOptions.confirm?.({
+        kind: "takeover_existing_server",
+        message: [
+            "Another Tutti host server or machine-local binding exists for this project.",
+            "",
+            `Current server: ${options.existingWorkspaceRoot}`,
+            `New workspace: ${options.newWorkspaceRoot}`,
+            "",
+            "Tutti can take over this project identity from the new workspace.",
+        ].join("\n"),
+    })) ?? false;
+    if (!accepted) {
+        throw new LaunchError("takeover_rejected", "Workspace root takeover requires confirmation", "Re-run with `--yes` or confirm the takeover prompt in an interactive terminal.");
+    }
+}
+function createSummary(options) {
+    const summary = {
+        status: options.status,
+        workspace_root: options.workspaceRoot,
+        project_id: options.projectId,
+        branch: TUTTI_MAINLINE_BRANCH,
+        relay_url: options.relayUrl,
+        local_diagnostic_endpoint: options.localDiagnosticEndpoint,
+    };
+    if (options.providerStatus !== undefined) {
+        summary.provider_status = options.providerStatus;
+    }
+    if (options.runtimeEndpoint !== undefined) {
+        summary.setup_url = setupUrl(options.runtimeEndpoint);
+    }
+    if (options.runtimeEndpoint !== undefined) {
+        summary.runtime_endpoint = endpointWithoutToken(options.runtimeEndpoint);
+    }
+    if (options.relay !== undefined) {
+        summary.relay = options.relay;
+    }
+    return summary;
+}
+export async function startLaunchProject(options) {
+    const context = resolveLaunchLocalContext(options);
+    const fetchImpl = options.fetch ?? fetch;
+    const probeRuntimeEndpoint = options.probeRuntimeEndpoint ?? createRuntimeEndpointProbe(fetchImpl);
+    const shutdownWaitMs = options.shutdownWaitMs ?? DEFAULT_SHUTDOWN_WAIT_MS;
+    let startupStatus = context.existing_identity.kind === "missing" ? "created" : "recovered";
+    let allowWorkspaceRootTakeover = false;
+    if (context.existing_identity.kind === "present") {
+        const projectId = context.existing_identity.project_id;
+        const endpoint = readMachineRuntimeEndpoint(context.tutti_home, projectId);
+        if (endpoint !== null) {
+            const sameWorkspace = resolve(endpoint.workspace_root) === context.workspace_root;
+            const probe = await probeRuntimeEndpoint(endpoint);
+            if (probe.kind === "alive" && sameWorkspace) {
+                const launchStatus = await readExistingHostLaunchStatus({ endpoint, fetchImpl });
+                const relay = relayStatusFromLocalStatus(launchStatus);
+                return {
+                    kind: "connected",
+                    summary: createSummary({
+                        status: "connected",
+                        workspaceRoot: context.workspace_root,
+                        projectId,
+                        relayUrl: context.relay_url,
+                        localDiagnosticEndpoint: endpoint.base_url,
+                        runtimeEndpoint: endpoint,
+                        ...(relay === undefined ? {} : { relay }),
+                    }),
+                };
+            }
+            if (probe.kind === "alive" && !sameWorkspace) {
+                await requireTakeoverConfirmation({
+                    existingWorkspaceRoot: endpoint.workspace_root,
+                    newWorkspaceRoot: context.workspace_root,
+                    launchOptions: options,
+                });
+                await requestExistingHostShutdown({
+                    endpoint,
+                    fetchImpl,
+                    probeRuntimeEndpoint,
+                    shutdownWaitMs,
+                });
+                deleteMachineRuntimeEndpoint({
+                    tuttiHome: context.tutti_home,
+                    projectId,
+                    expectedToken: endpoint.token,
+                });
+                startupStatus = "taken_over";
+                allowWorkspaceRootTakeover = true;
+            }
+            if (probe.kind === "stale") {
+                if (!sameWorkspace) {
+                    await requireTakeoverConfirmation({
+                        existingWorkspaceRoot: endpoint.workspace_root,
+                        newWorkspaceRoot: context.workspace_root,
+                        launchOptions: options,
+                    });
+                    startupStatus = "taken_over";
+                    allowWorkspaceRootTakeover = true;
+                }
+                deleteMachineRuntimeEndpoint({
+                    tuttiHome: context.tutti_home,
+                    projectId,
+                });
+            }
+        }
+        else {
+            const binding = readMachineProjectBinding(context.tutti_home, projectId);
+            if (binding !== null && resolve(binding.workspace_root) !== context.workspace_root) {
+                await requireTakeoverConfirmation({
+                    existingWorkspaceRoot: binding.workspace_root,
+                    newWorkspaceRoot: context.workspace_root,
+                    launchOptions: options,
+                });
+                startupStatus = "taken_over";
+                allowWorkspaceRootTakeover = true;
+            }
+        }
+    }
+    const preparation = await prepareLaunchProject({
+        ...options,
+        allowWorkspaceRootTakeover,
+    });
+    const launchStatus = {};
+    const refreshRelayJoinUrl = async () => {
+        if (launchStatus.relay === undefined) {
+            return relayStateFromLaunchStatus(preparation.relay_url, launchStatus);
+        }
+        const hostSecret = readHostRegistrationSecret(preparation.tutti_home, preparation.project_id);
+        const response = await refreshRelayJoinTokenWithRelay({
+            relayUrl: preparation.relay_url,
+            projectId: preparation.project_id,
+            relayProjectRef: launchStatus.relay.relay_project_ref,
+            hostConnectionRef: launchStatus.relay.host_connection_ref,
+            hostRegistrationSecret: hostSecret.secret,
+            joinToken: { mode: "rotate" },
+            fetch: fetchImpl,
+        });
+        const relayWithoutJoinUrl = { ...launchStatus.relay };
+        delete relayWithoutJoinUrl.join_url;
+        launchStatus.relay = {
+            ...relayWithoutJoinUrl,
+            ...(response.join_token.join_url === undefined
+                ? {}
+                : { join_url: response.join_token.join_url }),
+            join_url_visibility: response.join_token.visibility,
+            join_token_expires_at: response.join_token.expires_at,
+            join_token_reusable: response.join_token.reusable,
+        };
+        return relayStateFromLaunchStatus(preparation.relay_url, launchStatus);
+    };
+    const host = await startForegroundHostServer({
+        preparation,
+        endpointHost: context.local_diagnostic_endpoint.host,
+        endpointPort: context.local_diagnostic_endpoint.port,
+        createServer: options.createServer ?? createHostServer,
+        getLaunchStatus: () => launchStatus,
+        refreshRelayJoinUrl,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    let relay;
+    try {
+        const registered = await registerHostWithRelay({
+            preparation,
+            fetchImpl,
+            registerRelayHostConnection: options.registerRelayHostConnection ?? registerRelayHostConnectionWithRelay,
+            serverVersion: HOST_SERVER_VERSION,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+        relay = registered.summary;
+        launchStatus.relay = relay;
+        const tunnel = (options.connectRelayHostTunnel ?? connectRelayHostTunnel)({
+            tunnelUrl: relay.tunnel_url,
+            relayProjectRef: relay.relay_project_ref,
+            hostConnectionRef: relay.host_connection_ref,
+            hostConnectionToken: registered.hostConnectionToken,
+            handleRequest: createHostProjectApiTunnelRequestHandler({
+                app: host.app,
+                trustedMetadataStore: host.trusted_relay_metadata_store,
+            }),
+            handleStreamRequest: createHostProjectApiTunnelStreamRequestHandler({
+                baseUrl: host.runtime_endpoint.base_url,
+                trustedMetadataStore: host.trusted_relay_metadata_store,
+            }),
+        });
+        await tunnel.connected;
+        host.attachRelayTunnel(tunnel);
+    }
+    catch (error) {
+        const launchError = error instanceof LaunchError || error instanceof RelayHostControlClientError
+            ? relayErrorToLaunchError(error, preparation.relay_url)
+            : new LaunchError("relay_registration_failed", error instanceof Error
+                ? `Relay host tunnel failed: ${error.message}`
+                : "Relay host tunnel failed", "Retry `tutti launch`; if it keeps failing, inspect Relay tunnel logs.");
+        try {
+            await host.close();
+        }
+        catch {
+            // Preserve the Relay failure as the actionable launch error.
+        }
+        throw launchError;
+    }
+    return {
+        kind: "hosting",
+        preparation,
+        host,
+        summary: createSummary({
+            status: startupStatus,
+            workspaceRoot: preparation.workspace_root,
+            projectId: preparation.project_id,
+            relayUrl: preparation.relay_url,
+            localDiagnosticEndpoint: host.runtime_endpoint.base_url,
+            providerStatus: preparation.provider_status,
+            runtimeEndpoint: host.runtime_endpoint,
+            relay,
+        }),
+    };
+}
+export function formatLaunchLifecycleResult(result) {
+    const summary = result.summary;
+    const fields = [
+        result.kind === "connected"
+            ? "Tutti project host is already running"
+            : "Tutti project host is running",
+        "",
+        `Status: ${summary.status}`,
+        `Workspace: ${redactText(summary.workspace_root)}`,
+        `Project: ${summary.project_id}`,
+        `Branch: ${summary.branch}`,
+        `Relay: ${summary.relay_url}`,
+    ];
+    if (summary.provider_status !== undefined) {
+        fields.push(`Provider: ${summary.provider_status}`);
+    }
+    fields.push(`Local diagnostic endpoint: ${summary.local_diagnostic_endpoint}`);
+    if (summary.setup_url !== undefined) {
+        fields.push(`Setup URL: ${summary.setup_url}`);
+    }
+    if (summary.relay?.join_url !== undefined) {
+        fields.push(`Join URL: ${summary.relay.join_url}`);
+    }
+    else if (summary.relay?.join_url_visibility === "not_recoverable") {
+        fields.push("Join URL: not recoverable; rotate a fresh invite from the host.");
+    }
+    else {
+        fields.push("Join URL: unavailable from this local host process");
+    }
+    fields.push("");
+    fields.push(result.kind === "connected"
+        ? "An existing host server is handling this workspace; no second server was started."
+        : "This terminal is hosting the project server. Press Ctrl-C to stop.");
+    return fields.join("\n");
+}
+export async function waitForForegroundHostShutdown(handle, processLike = process) {
+    const stop = () => {
+        void handle.close();
+    };
+    processLike.once("SIGINT", stop);
+    processLike.once("SIGTERM", stop);
+    try {
+        await handle.closed;
+    }
+    finally {
+        processLike.off("SIGINT", stop);
+        processLike.off("SIGTERM", stop);
+    }
+}
+//# sourceMappingURL=host-lifecycle.js.map

package/dist/server-shell/cli/host-relay-status.d.ts

@@ -0,0 +1,6 @@
+import type { HostLocalLaunchStatus } from "../http/routes/local-control.js";
+import type { HostWorkspaceRelayState } from "../http/routes/project-api.js";
+import type { HostLaunchRelaySummary } from "./relay-registration.js";
+export declare function relayStateFromLaunchStatus(relayUrl: string, status: HostLocalLaunchStatus | undefined): HostWorkspaceRelayState;
+export declare function relayStatusFromLocalStatus(status: HostLocalLaunchStatus): HostLaunchRelaySummary | undefined;
+//# sourceMappingURL=host-relay-status.d.ts.map

package/dist/server-shell/cli/host-relay-status.js

@@ -0,0 +1,43 @@
+import { ID_PREFIXES, isPrefixedId, } from "@tutti/shared/ids";
+export function relayStateFromLaunchStatus(relayUrl, status) {
+    if (status?.relay === undefined) {
+        return {
+            status: "unavailable",
+            relay_url: relayUrl,
+            join_token_reusable: true,
+        };
+    }
+    return {
+        status: "connected",
+        relay_url: relayUrl,
+        relay_project_ref: status.relay.relay_project_ref,
+        ...(status.relay.join_url === undefined ? {} : { join_url: status.relay.join_url }),
+        join_url_visibility: status.relay.join_url_visibility,
+        ...(status.relay.join_token_expires_at === undefined
+            ? {}
+            : { join_token_expires_at: status.relay.join_token_expires_at }),
+        join_token_reusable: status.relay.join_token_reusable ?? true,
+    };
+}
+export function relayStatusFromLocalStatus(status) {
+    if (status.relay === undefined) {
+        return undefined;
+    }
+    if (!isPrefixedId(status.relay.relay_project_ref, ID_PREFIXES.relayProject) ||
+        !isPrefixedId(status.relay.host_connection_ref, ID_PREFIXES.hostConnection)) {
+        return undefined;
+    }
+    return {
+        relay_project_ref: status.relay.relay_project_ref,
+        host_connection_ref: status.relay.host_connection_ref,
+        ...(status.relay.join_url === undefined ? {} : { join_url: status.relay.join_url }),
+        join_url_visibility: status.relay.join_url_visibility,
+        ...(status.relay.join_token_expires_at === undefined
+            ? {}
+            : { join_token_expires_at: status.relay.join_token_expires_at }),
+        join_token_reusable: status.relay.join_token_reusable ?? true,
+        tunnel_url: status.relay.tunnel_url,
+        connected_at: status.relay.connected_at,
+    };
+}
+//# sourceMappingURL=host-relay-status.js.map

package/dist/server-shell/cli/host-runtime-endpoint.d.ts

@@ -0,0 +1,22 @@
+import type { HostLocalLaunchStatus } from "../http/routes/local-control.js";
+import type { MachineRuntimeEndpointRecord } from "./machine-local.js";
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export type HostRuntimeEndpointProbeResult = {
+    kind: "alive";
+} | {
+    kind: "stale";
+    reason: string;
+};
+export type HostRuntimeEndpointProbe = (endpoint: MachineRuntimeEndpointRecord) => Promise<HostRuntimeEndpointProbeResult>;
+export declare function createRuntimeEndpointProbe(fetchImpl?: FetchLike): HostRuntimeEndpointProbe;
+export declare function requestExistingHostShutdown(options: {
+    endpoint: MachineRuntimeEndpointRecord;
+    fetchImpl: FetchLike;
+    probeRuntimeEndpoint: HostRuntimeEndpointProbe;
+    shutdownWaitMs: number;
+}): Promise<void>;
+export declare function readExistingHostLaunchStatus(options: {
+    endpoint: MachineRuntimeEndpointRecord;
+    fetchImpl: FetchLike;
+}): Promise<HostLocalLaunchStatus>;
+//# sourceMappingURL=host-runtime-endpoint.d.ts.map

package/dist/server-shell/cli/host-runtime-endpoint.js

@@ -0,0 +1,120 @@
+import { LaunchError } from "./errors.js";
+const DEFAULT_PROBE_TIMEOUT_MS = 1_000;
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function isHostHealthPayload(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return record.service === "tutti-host" && record.status === "ok";
+}
+async function fetchWithTimeout(fetchImpl, url, init = {}, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        return await fetchImpl(url, {
+            ...init,
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export function createRuntimeEndpointProbe(fetchImpl = fetch) {
+    return async (endpoint) => {
+        try {
+            const response = await fetchWithTimeout(fetchImpl, new URL("/health", endpoint.base_url), {
+                headers: {
+                    accept: "application/json",
+                },
+            });
+            if (!response.ok) {
+                return { kind: "stale", reason: `health returned HTTP ${response.status}` };
+            }
+            const payload = await response.json();
+            if (!isHostHealthPayload(payload)) {
+                return { kind: "stale", reason: "health response is not a Tutti host" };
+            }
+            return { kind: "alive" };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : "health check failed";
+            return { kind: "stale", reason };
+        }
+    };
+}
+export async function requestExistingHostShutdown(options) {
+    let response;
+    try {
+        response = await fetchWithTimeout(options.fetchImpl, new URL("/host-local/v1/shutdown", options.endpoint.base_url), {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${options.endpoint.token}`,
+            },
+        });
+    }
+    catch {
+        throw new LaunchError("takeover_failed", "The existing host server did not accept the takeover shutdown request", "Stop the existing host server manually, then run `tutti launch` again.");
+    }
+    if (!response.ok) {
+        throw new LaunchError("takeover_failed", `The existing host server rejected takeover shutdown with HTTP ${response.status}`, "Stop the existing host server manually, then run `tutti launch` again.");
+    }
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < options.shutdownWaitMs) {
+        const probe = await options.probeRuntimeEndpoint(options.endpoint);
+        if (probe.kind === "stale") {
+            return;
+        }
+        await delay(50);
+    }
+    throw new LaunchError("takeover_failed", "The existing host server did not stop before the takeover timeout", "Stop the existing host server manually, then run `tutti launch` again.");
+}
+function isLaunchStatusPayload(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    if (record.relay === undefined) {
+        return true;
+    }
+    if (typeof record.relay !== "object" || record.relay === null || Array.isArray(record.relay)) {
+        return false;
+    }
+    const relay = record.relay;
+    const visibility = relay.join_url_visibility;
+    return (typeof relay.relay_project_ref === "string" &&
+        typeof relay.host_connection_ref === "string" &&
+        (relay.join_url === undefined || typeof relay.join_url === "string") &&
+        (visibility === "visible_once" || visibility === "not_recoverable") &&
+        (relay.join_token_expires_at === undefined ||
+            typeof relay.join_token_expires_at === "string") &&
+        (relay.join_token_reusable === undefined || typeof relay.join_token_reusable === "boolean") &&
+        typeof relay.tunnel_url === "string" &&
+        typeof relay.connected_at === "string");
+}
+export async function readExistingHostLaunchStatus(options) {
+    try {
+        const response = await fetchWithTimeout(options.fetchImpl, new URL("/host-local/v1/launch-status", options.endpoint.base_url), {
+            headers: {
+                accept: "application/json",
+                authorization: `Bearer ${options.endpoint.token}`,
+            },
+        });
+        if (!response.ok) {
+            return {};
+        }
+        const payload = await response.json();
+        return isLaunchStatusPayload(payload) ? payload : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=host-runtime-endpoint.js.map

package/dist/server-shell/cli/host-server-runtime.d.ts

@@ -0,0 +1,30 @@
+import type { FastifyInstance } from "fastify";
+import { type RelayHostTunnelHandle } from "@tutti/relay-client";
+import { type HostProjectStore } from "../../store/index.js";
+import type { createHostServer } from "../http/create-server.js";
+import type { HostLocalLaunchStatus } from "../http/routes/local-control.js";
+import type { HostWorkspaceRelayState } from "../http/routes/project-api/types.js";
+import { type TrustedRelaySessionMetadataStore } from "../session/relay-session-context.js";
+import type { LaunchPreparationResult } from "./launch.js";
+import { type MachineRuntimeEndpointRecord } from "./machine-local.js";
+export declare const HOST_SERVER_VERSION = "0.0.0";
+export type HostServerFactory = typeof createHostServer;
+export type HostServerHandle = {
+    app: FastifyInstance;
+    store: HostProjectStore;
+    runtime_endpoint: MachineRuntimeEndpointRecord;
+    trusted_relay_metadata_store: TrustedRelaySessionMetadataStore;
+    attachRelayTunnel: (tunnel: RelayHostTunnelHandle) => void;
+    closed: Promise<void>;
+    close: () => Promise<void>;
+};
+export declare function startForegroundHostServer(options: {
+    preparation: LaunchPreparationResult;
+    endpointHost: string;
+    endpointPort: number;
+    createServer: HostServerFactory;
+    getLaunchStatus?: () => HostLocalLaunchStatus;
+    refreshRelayJoinUrl?: () => Promise<HostWorkspaceRelayState>;
+    now?: () => Date;
+}): Promise<HostServerHandle>;
+//# sourceMappingURL=host-server-runtime.d.ts.map