summer-engine 3.2.1 → 3.4.0

package/dist/core/hosted-mcp.d.ts

@@ -0,0 +1,115 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+/** The part of an MCP client the mount and the CLI use (a fake in tests). */
+export interface HostedClient {
+    listTools(params?: {
+        cursor?: string;
+    }): Promise<{
+        tools: Tool[];
+        nextCursor?: string;
+    }>;
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    listPrompts(params?: {
+        cursor?: string;
+    }): Promise<{
+        prompts: Array<{
+            name: string;
+            title?: string;
+            description?: string;
+            arguments?: Array<{
+                name: string;
+                description?: string;
+                required?: boolean;
+            }>;
+        }>;
+        nextCursor?: string;
+    }>;
+    getPrompt(params: {
+        name: string;
+        arguments?: Record<string, string>;
+    }): Promise<Record<string, unknown>>;
+    listResources(params?: {
+        cursor?: string;
+    }): Promise<{
+        resources: Array<{
+            uri: string;
+            name: string;
+            title?: string;
+            description?: string;
+            mimeType?: string;
+        }>;
+        nextCursor?: string;
+    }>;
+    readResource(params: {
+        uri: string;
+    }): Promise<Record<string, unknown>>;
+    close?(): Promise<void>;
+}
+export interface HostedConnectDependencies {
+    /** The hosted Summer Engine MCP URL (the store sign-in's resource). */
+    url: () => string;
+    token: () => Promise<string>;
+    connect: (url: string, token: () => Promise<string>) => Promise<HostedClient>;
+}
+export declare function connectHostedMcp(url: string, token: () => Promise<string>): Promise<HostedClient>;
+export declare const defaultHostedConnectDependencies: HostedConnectDependencies;
+/** True when this machine has a store sign-in on disk (no network). */
+export declare function hasStoreSignIn(): Promise<boolean>;
+export declare function listAllHostedTools(client: HostedClient): Promise<Tool[]>;
+/** Connect with the store sign-in, run fn, close. Throws OAuthError when not signed in. */
+export declare function withHostedMcp<T>(fn: (client: HostedClient) => Promise<T>, deps?: HostedConnectDependencies): Promise<T>;
+/** The text of a tool result, parsed as JSON when it is JSON. */
+export declare function hostedResultPayload(result: Record<string, unknown>): {
+    isError: boolean;
+    text: string;
+    json: Record<string, unknown> | null;
+};
+export type StoreAccessResult = {
+    status: "not_signed_in";
+    message: string;
+} | {
+    status: "ok";
+    games: number | null;
+} | {
+    status: "refused";
+    code: string | null;
+    message: string;
+    requestId?: string;
+} | {
+    status: "unreachable";
+    message: string;
+};
+/**
+ * Ask the store for the creator's games through the hosted MCP
+ * (summer_store_list_games): proves the store accepts this machine's sign-in.
+ */
+export declare function checkStoreAccess(timeoutMs?: number, deps?: HostedConnectDependencies): Promise<StoreAccessResult>;
+/** The hosted tool a CLI name means: the exact name, or a slug ("store-list-games" -> summer_store_list_games). */
+export declare function matchHostedTool(name: string, tools: readonly Tool[]): Tool | null;
+export type HostedToolsListing = {
+    status: "listed";
+    tools: Tool[];
+} | {
+    status: "not_signed_in";
+} | {
+    status: "unavailable";
+    message: string;
+};
+/** The hosted store and publishing tools, when this machine has a store sign-in. */
+export declare function listHostedToolsForCli(deps?: HostedConnectDependencies, signedIn?: () => Promise<boolean>): Promise<HostedToolsListing>;
+export type HostedCallOutcome = {
+    status: "called";
+    tool: string;
+    result: Record<string, unknown>;
+} | {
+    status: "not_found";
+} | {
+    status: "not_signed_in";
+} | {
+    status: "unavailable";
+    message: string;
+};
+/** Call a hosted tool by its name or slug with the store sign-in (one connection). */
+export declare function callHostedToolForCli(name: string, args: Record<string, unknown>, deps?: HostedConnectDependencies, signedIn?: () => Promise<boolean>): Promise<HostedCallOutcome>;

package/dist/core/hosted-mcp.js

@@ -0,0 +1,164 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { getStoreAccessToken, OAuthError, readStoredOAuthToken, resolveMcpResourceUrl } from "./oauth.js";
+import { TOOLKIT_VERSION } from "./version.js";
+/**
+ * A client for the hosted Summer Engine MCP (mcp.summerengine.com), signed in
+ * with the store sign-in ("summer login --store"). The local MCP mounts its
+ * tools (src/mcp/hosted-mount.ts); `summer tool` and `summer doctor` call it
+ * directly through the helpers below, so all three faces reach the same
+ * store and publishing tools.
+ */
+const CALL_TIMEOUT_MS = 120_000;
+export async function connectHostedMcp(url, token) {
+    const transport = new StreamableHTTPClientTransport(new URL(url), {
+        // A fresh (refreshed when near expiry) token on every request.
+        fetch: async (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set("authorization", `Bearer ${await token()}`);
+            return fetch(input, { ...init, headers });
+        },
+    });
+    const client = new Client({ name: "summer-engine-local", version: TOOLKIT_VERSION });
+    await client.connect(transport);
+    const timeout = { timeout: CALL_TIMEOUT_MS };
+    return {
+        listTools: (params) => client.listTools(params),
+        callTool: (params) => client.callTool(params, undefined, timeout),
+        listPrompts: (params) => client.listPrompts(params),
+        getPrompt: (params) => client.getPrompt(params),
+        listResources: (params) => client.listResources(params),
+        readResource: (params) => client.readResource(params),
+        close: () => client.close(),
+    };
+}
+export const defaultHostedConnectDependencies = {
+    url: () => resolveMcpResourceUrl(),
+    token: () => getStoreAccessToken(),
+    connect: connectHostedMcp,
+};
+/** True when this machine has a store sign-in on disk (no network). */
+export async function hasStoreSignIn() {
+    return (await readStoredOAuthToken()) !== null;
+}
+export async function listAllHostedTools(client) {
+    const out = [];
+    let cursor;
+    for (let pages = 0; pages < 20; pages++) {
+        const result = await client.listTools(cursor ? { cursor } : undefined);
+        out.push(...(result.tools ?? []));
+        if (!result.nextCursor)
+            break;
+        cursor = result.nextCursor;
+    }
+    return out;
+}
+/** Connect with the store sign-in, run fn, close. Throws OAuthError when not signed in. */
+export async function withHostedMcp(fn, deps = defaultHostedConnectDependencies) {
+    const url = deps.url();
+    await deps.token();
+    const client = await deps.connect(url, deps.token);
+    try {
+        return await fn(client);
+    }
+    finally {
+        await client.close?.().catch(() => undefined);
+    }
+}
+/** The text of a tool result, parsed as JSON when it is JSON. */
+export function hostedResultPayload(result) {
+    const content = Array.isArray(result.content) ? result.content : [];
+    const text = content
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("\n");
+    let json = null;
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            json = parsed;
+    }
+    catch {
+        json = null;
+    }
+    if (!json && result.structuredContent && typeof result.structuredContent === "object") {
+        json = result.structuredContent;
+    }
+    return { isError: result.isError === true, text, json };
+}
+/**
+ * Ask the store for the creator's games through the hosted MCP
+ * (summer_store_list_games): proves the store accepts this machine's sign-in.
+ */
+export async function checkStoreAccess(timeoutMs = 8_000, deps = defaultHostedConnectDependencies) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ status: "unreachable", message: `no answer within ${Math.round(timeoutMs / 1000)} s` }), timeoutMs);
+        timer.unref?.();
+    });
+    const attempt = (async () => {
+        try {
+            const result = await withHostedMcp((client) => client.callTool({ name: "summer_store_list_games", arguments: {} }), deps);
+            const payload = hostedResultPayload(result);
+            if (payload.isError || payload.json?.ok === false) {
+                const code = typeof payload.json?.code === "string" ? payload.json.code : typeof payload.json?.error === "string" ? payload.json.error : null;
+                const message = typeof payload.json?.message === "string" ? payload.json.message : payload.text.slice(0, 300) || "the store refused the call";
+                const requestId = typeof payload.json?.requestId === "string" ? payload.json.requestId : undefined;
+                return { status: "refused", code, message, ...(requestId ? { requestId } : {}) };
+            }
+            const games = Array.isArray(payload.json?.games) ? payload.json.games.length : null;
+            return { status: "ok", games };
+        }
+        catch (error) {
+            if (error instanceof OAuthError && error.code === "store_login_required") {
+                return { status: "not_signed_in", message: error.message.replace(` ${error.recovery}`, "") };
+            }
+            if (error instanceof OAuthError)
+                return { status: "refused", code: error.code, message: error.message };
+            return { status: "unreachable", message: error instanceof Error ? error.message : String(error) };
+        }
+    })();
+    try {
+        return await Promise.race([attempt, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The hosted tool a CLI name means: the exact name, or a slug ("store-list-games" -> summer_store_list_games). */
+export function matchHostedTool(name, tools) {
+    const needle = name.trim();
+    const asAlias = needle.startsWith("summer_") ? needle : `summer_${needle.replace(/-/g, "_")}`;
+    return tools.find((tool) => tool.name === needle) ?? tools.find((tool) => tool.name === asAlias) ?? null;
+}
+/** The hosted store and publishing tools, when this machine has a store sign-in. */
+export async function listHostedToolsForCli(deps = defaultHostedConnectDependencies, signedIn = hasStoreSignIn) {
+    if (!(await signedIn()))
+        return { status: "not_signed_in" };
+    try {
+        return { status: "listed", tools: await withHostedMcp(listAllHostedTools, deps) };
+    }
+    catch (error) {
+        if (error instanceof OAuthError && error.code === "store_login_required")
+            return { status: "not_signed_in" };
+        return { status: "unavailable", message: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Call a hosted tool by its name or slug with the store sign-in (one connection). */
+export async function callHostedToolForCli(name, args, deps = defaultHostedConnectDependencies, signedIn = hasStoreSignIn) {
+    if (!(await signedIn()))
+        return { status: "not_signed_in" };
+    try {
+        return await withHostedMcp(async (client) => {
+            const tool = matchHostedTool(name, await listAllHostedTools(client));
+            if (!tool)
+                return { status: "not_found" };
+            return { status: "called", tool: tool.name, result: await client.callTool({ name: tool.name, arguments: args }) };
+        }, deps);
+    }
+    catch (error) {
+        if (error instanceof OAuthError && error.code === "store_login_required")
+            return { status: "not_signed_in" };
+        return { status: "unavailable", message: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/core/launch-posture.d.ts

@@ -96,6 +96,9 @@ export type BackgroundLaunchSupport = {
     reason: "version_unknown";
     version: null;
 };
+/** Whether `version` is `minimum` or newer; null when either is missing or
+ *  not x.y.z (an unknown version is never "too old" and never "new enough"). */
+export declare function isVersionAtLeast(version: string | null | undefined, minimum: string): boolean | null;
 /**
  * Whether the installed engine honours the background flag. The `--help`
  * probe answer (true/false) is definitive when it ran; a probe that could not

package/dist/core/launch-posture.js

@@ -61,7 +61,7 @@
  * --help probe below runs against THAT binary (cache key: path + mtime + size).
  */
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { platform } from "node:os";
 import { getSummerDir } from "./auth.js";
@@ -100,6 +100,15 @@ function compareVersions(a, b) {
         return a.minor - b.minor;
     return a.patch - b.patch;
 }
+/** Whether `version` is `minimum` or newer; null when either is missing or
+ *  not x.y.z (an unknown version is never "too old" and never "new enough"). */
+export function isVersionAtLeast(version, minimum) {
+    const parsed = version ? parseVersion(version) : null;
+    const min = parseVersion(minimum);
+    if (!parsed || !min)
+        return null;
+    return compareVersions(parsed, min) >= 0;
+}
 /**
  * Whether the installed engine honours the background flag. The `--help`
  * probe answer (true/false) is definitive when it ran; a probe that could not
@@ -282,12 +291,16 @@ export function parseVelopackVersion(sqVersionText) {
     const match = sqVersionText.match(/<version>\s*([^<\s]+)\s*<\/version>/i);
     return match ? match[1].trim() : null;
 }
-/** Walk up from `.../Summer.app/Contents/MacOS/Summer` to the bundle. */
+/** Walk up from `.../Summer.app/Contents/MacOS/Summer` to the bundle. A
+ *  bundle unpacked without its `.app` folder (`<dir>/Contents/MacOS/Summer`)
+ *  reads as `<dir>`. */
 function macBundlePathFor(binary) {
     let current = dirname(binary);
     for (let depth = 0; depth < 4; depth++) {
         if (basename(current).endsWith(".app"))
             return current;
+        if (basename(current) === "Contents" && existsSync(join(current, "Info.plist")))
+            return dirname(current);
         const parent = dirname(current);
         if (parent === current)
             break;

package/dist/core/library-read.d.ts

@@ -19,10 +19,10 @@ export declare const readLibraryInputSchema: z.ZodObject<{
     part: z.ZodOptional<z.ZodEnum<["skill", "resource", "all"]>>;
 }, "strict", z.ZodTypeAny, {
     id: string;
-    part?: "all" | "resource" | "skill" | undefined;
+    part?: "resource" | "all" | "skill" | undefined;
 }, {
     id: string;
-    part?: "all" | "resource" | "skill" | undefined;
+    part?: "resource" | "all" | "skill" | undefined;
 }>;
 export type ReadLibraryArgs = z.infer<typeof readLibraryInputSchema>;
 export interface LibraryReadDeps extends LibrarySearchDeps {

package/dist/core/oauth.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The Summer store sign-in for local tools (summer_publish_build): OAuth 2.1
+ * authorization code + PKCE against the same Supabase authorization server
+ * and resource the hosted MCP uses (mcp.summerengine.com/mcp), with a
+ * loopback redirect (RFC 8252). The access token's audience is the MCP
+ * resource, the one token the creator store accepts for agents (creator
+ * publishing spec, part C.3).
+ *
+ * The Summer CLI is one public client (no secret; PKCE proves each login).
+ * The authorization server matches redirect URIs exactly, so the CLI listens
+ * on one of a few fixed loopback ports and registers its client once per
+ * machine with exactly those redirect URIs. Later logins and refreshes reuse
+ * that client id (~/.summer/oauth-client); only --force registers anew.
+ *
+ * The token is stored in ~/.summer/oauth-token (0600) with its refresh token,
+ * separate from the CLI JWT in auth-token: the engine reads that file and
+ * expects the summer-cli contract.
+ */
+export declare const OAUTH_TOKEN_FILE = "oauth-token";
+export declare const OAUTH_CLIENT_FILE = "oauth-client";
+/** Loopback ports the Summer CLI client is registered for, tried in order. */
+export declare const STORE_LOGIN_PORTS: readonly [47615, 47616, 47617];
+export declare const DEFAULT_MCP_RESOURCE_URL = "https://mcp.summerengine.com/mcp";
+export declare const MCP_RESOURCE_ENV = "SUMMER_MCP_RESOURCE_URL";
+export declare class OAuthError extends Error {
+    readonly code: string;
+    readonly recovery: string;
+    constructor(code: string, message: string, recovery: string);
+}
+export interface StoredOAuthToken {
+    schemaVersion: 1;
+    resource: string;
+    issuer: string;
+    tokenEndpoint: string;
+    clientId: string;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: string;
+    scope?: string;
+}
+/** The machine's registered Summer CLI client for one authorization server. */
+export interface StoredOAuthClient {
+    schemaVersion: 1;
+    issuer: string;
+    clientId: string;
+    redirectUris: string[];
+}
+interface AuthorizationServer {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint: string;
+}
+export interface OAuthDependencies {
+    fetch: typeof fetch;
+    now: () => number;
+}
+export declare function resolveMcpResourceUrl(env?: NodeJS.ProcessEnv): string;
+/** RFC 9728 resource metadata, then RFC 8414 server metadata (path-aware first). */
+export declare function discoverAuthorizationServer(resource: string, deps?: OAuthDependencies): Promise<AuthorizationServer>;
+export interface StoreLoginDependencies extends OAuthDependencies {
+    openUrl: (url: string) => Promise<unknown>;
+    log: (message: string) => void;
+    timeoutMs?: number;
+    /** Register a new client instead of reusing this machine's ("summer login --store --force"). */
+    newClient?: boolean;
+    /** Tests only: other loopback ports. */
+    ports?: readonly number[];
+}
+/** Browser sign-in (authorization code + PKCE) that stores ~/.summer/oauth-token. */
+export declare function runStoreLogin(deps: StoreLoginDependencies): Promise<StoredOAuthToken>;
+export declare function readStoredOAuthToken(): Promise<StoredOAuthToken | null>;
+/**
+ * A current store access token: the stored one, refreshed when it expires
+ * within a minute.
+ */
+export declare function getStoreAccessToken(deps?: OAuthDependencies): Promise<string>;
+export {};