applaunchflow 0.3.1

package/build/tools/projects.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { fail, ok } from "./utils.js";
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+export function registerProjectTools(server, client) {
+    server.registerTool("list_projects", {
+        title: "List Projects",
+        description: "List AppLaunchFlow projects for the authenticated user",
+    }, async () => {
+        try {
+            return ok(await client.listProjects(), "Fetched projects");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("get_project", {
+        title: "Get Project",
+        description: "Get the full hub state for a project",
+        inputSchema: {
+            projectId: z.string().uuid(),
+        },
+    }, async ({ projectId }) => {
+        try {
+            return ok(await client.getProject(projectId), "Fetched project");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("create_project", {
+        title: "Create Project",
+        description: "Create a new AppLaunchFlow project. Only app name and platform are required. " +
+            "Autofill category and description from context when possible — do not ask the user for these unless genuinely ambiguous.",
+        inputSchema: {
+            appName: z
+                .string()
+                .trim()
+                .min(1)
+                .max(120)
+                .describe("The app name."),
+            platform: z
+                .enum(["ios", "android", "both"])
+                .optional()
+                .describe("Target platform. Defaults to iOS."),
+            category: z
+                .string()
+                .trim()
+                .max(120)
+                .optional()
+                .describe("App category. Infer from the app name/context when possible (e.g. 'Travel' for a flight app)."),
+            appDescription: z
+                .string()
+                .trim()
+                .max(4000)
+                .optional()
+                .describe("Brief app description. Infer from context when possible."),
+            defaultDeviceType: z
+                .enum(["phone", "tablet", "desktop", "watch"])
+                .optional()
+                .describe("Defaults to phone. Only set if the user explicitly asks."),
+            logoPath: z
+                .string()
+                .optional()
+                .describe("Optional stored logo path from upload_screenshots when fileType=logo."),
+            metadata: z
+                .record(z.any())
+                .optional()
+                .describe("Advanced escape hatch for extra metadata fields."),
+        },
+    }, async (args) => {
+        try {
+            const platform = args.platform || "ios";
+            const metadata = stripUndefined({
+                ...(args.metadata || {}),
+                appName: args.appName,
+                platform,
+                category: args.category,
+                appDescription: args.appDescription,
+                defaultDeviceType: args.defaultDeviceType || "phone",
+                logoPath: args.logoPath,
+            });
+            const requestBody = stripUndefined({
+                name: args.appName,
+                platform,
+                metadata,
+            });
+            const created = await client.createProject(requestBody);
+            return ok({
+                project: created.project,
+                nextRecommendedStep: "upload_screenshots",
+            }, "Created project");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("delete_project", {
+        title: "Delete Project",
+        description: "Delete a project",
+        inputSchema: {
+            projectId: z.string().uuid(),
+        },
+    }, async ({ projectId }) => {
+        try {
+            return ok(await client.deleteProject(projectId), "Deleted project");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/build/tools/promovideo.js

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import { createHostedReadReceipt, createReadReceiptStore, fail, hostedMcpEnabled, ok, openUrl, verifyHostedReadReceipt, } from "./utils.js";
+const promoReceiptKey = (generationId, variantId) => ["promo-video", generationId, variantId || "active"].join("::");
+function buildPromoVideoEditorUrl(client, args) {
+    const params = new URLSearchParams({ projectId: args.generationId });
+    if (args.variantId) {
+        params.set("variantId", args.variantId);
+    }
+    return `${client.credentials.baseUrl}/promovideo?${params.toString()}`;
+}
+export function registerPromoVideoTools(server, client) {
+    const promoVideoReadReceipts = createReadReceiptStore();
+    server.registerTool("generate_promo_video", {
+        title: "Generate Promo Video",
+        description: "Run AI generation against the project's screenshots and produce a complete Remotion promo video config. " +
+            "Omit variantId so a new variant is always created — never overwrite an existing promo-video variant. " +
+            "After generation, the promo video editor opens automatically. " +
+            "Use selectedScreenshotIndices to constrain which uploaded screenshots feed the LLM. " +
+            "Use the optional message field to pass natural-language regeneration feedback when iterating on an existing variant.",
+        inputSchema: {
+            projectId: z.string().uuid().describe("Project / generation UUID."),
+            message: z
+                .string()
+                .optional()
+                .describe("Optional natural-language feedback for regeneration. Only meaningful when iterating on an existing variant."),
+            variantId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("DO NOT pass this for fresh takes. Only set when explicitly regenerating an existing variant."),
+            selectedScreenshotIndices: z
+                .array(z.number().int().min(0))
+                .optional()
+                .describe("Optional indices into the project's screenshots array. If omitted, the generator uses the project's default platform set."),
+        },
+    }, async (args, extra) => {
+        try {
+            const result = await client.generatePromoVideo(args);
+            const variantId = result?.variantId || args.variantId || "";
+            const editorUrl = buildPromoVideoEditorUrl(client, {
+                generationId: args.projectId,
+                variantId,
+            });
+            await openUrl(server, editorUrl, "Opening the generated promo video in the editor.", { signal: extra.signal });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Generated promo video successfully.",
+                            `Editor URL: ${editorUrl}`,
+                            "IMPORTANT: Paste this exact editor URL in the reply so the user can open it.",
+                        ].join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: { ...result, editorUrl },
+                    message: "Generated promo video",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("get_promo_video", {
+        title: "Get Promo Video",
+        description: "Fetch the current promo video config (Remotion VideoConfig) for a project. Required before update_promo_video so edits operate on fresh state. " +
+            "The returned object follows the schema in the resource applaunchflow://schema/video-config — read that resource to learn which fields and scene types exist and their valid ranges, not just which ones this config happens to use.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            variantId: z.string().uuid().optional(),
+        },
+    }, async ({ generationId, variantId }) => {
+        try {
+            const result = await client.getPromoVideo(generationId, variantId);
+            const editorUrl = buildPromoVideoEditorUrl(client, {
+                generationId,
+                variantId,
+            });
+            promoVideoReadReceipts.record({ generationId, variantId });
+            const readReceipt = hostedMcpEnabled()
+                ? createHostedReadReceipt(promoReceiptKey(generationId, variantId), client.credentials.token)
+                : undefined;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Fetched promo video.",
+                            `Editor URL: ${editorUrl}`,
+                            "A fresh read receipt was recorded and can be used for one update_promo_video call.",
+                        ].join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        ...result,
+                        editorUrl,
+                        readBeforeEditSatisfied: true,
+                        readReceipt,
+                    },
+                    message: "Fetched promo video",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("update_promo_video", {
+        title: "Update Promo Video",
+        description: "Persist a promo video config (the same Remotion VideoConfig shape returned by get_promo_video / generate_promo_video). " +
+            "This is a full-config replace — fetch the current config with get_promo_video, mutate the parts you want to change, then call this tool with the updated object. " +
+            "There is no granular scene-level transform; whole-config replace is the supported edit path at this stage. " +
+            "ENFORCED: each call requires a fresh get_promo_video for the same projectId/variantId immediately beforehand. " +
+            "SCHEMA REFERENCE: read the resource applaunchflow://schema/video-config for the full field-level reference — the six scene types and their content shapes, theme, TextStyle, ken burns, choreography preset ids, devices, overlays, and audio. " +
+            "Values outside the documented ranges fail validation and reject the whole update.",
+        inputSchema: {
+            projectId: z.string().uuid(),
+            variantId: z.string().uuid().optional(),
+            config: z
+                .record(z.any())
+                .describe("Full Remotion VideoConfig object — a whole-config replace, not a patch. " +
+                "Required: theme (colors + typography) and scenes (at least one; each scene is a discriminated union on `type`: hook | feature | text-only | closeup | multi-phone | cta, with a matching `content` shape). " +
+                "Optional: version, duration (seconds), audio, phoneId. " +
+                "All coordinates are percentages of the frame (0-100, 50 = centered), never pixels. " +
+                "Always start from the object returned by get_promo_video and mutate it — do not hand-build one. " +
+                "Full field reference including every scene's content fields and valid ranges: read the resource applaunchflow://schema/video-config."),
+            appName: z.string().optional(),
+            projectName: z.string().optional(),
+            readReceipt: z
+                .string()
+                .optional()
+                .describe("Hosted connector only: pass the readReceipt returned by the immediately preceding get_promo_video call."),
+        },
+    }, async (args) => {
+        try {
+            const receiptArgs = {
+                generationId: args.projectId,
+                variantId: args.variantId,
+            };
+            const hasReceipt = hostedMcpEnabled()
+                ? verifyHostedReadReceipt(args.readReceipt, promoReceiptKey(args.projectId, args.variantId), client.credentials.token)
+                : promoVideoReadReceipts.has(receiptArgs);
+            if (!hasReceipt) {
+                return fail(new Error("Call get_promo_video first for this project/variant before update_promo_video. Direct editing is locked until the current state has been read."));
+            }
+            const { readReceipt: _readReceipt, ...updateArgs } = args;
+            const result = await client.updatePromoVideo(updateArgs);
+            promoVideoReadReceipts.consume(receiptArgs);
+            const editorUrl = buildPromoVideoEditorUrl(client, {
+                generationId: args.projectId,
+                variantId: args.variantId,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Updated promo video.",
+                            `Editor URL (already open — do NOT run \`open\` again): ${editorUrl}`,
+                            "This update consumed the current read receipt. Call get_promo_video again before the next direct edit.",
+                        ].join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        result,
+                        editorUrl,
+                        nextEditRequiresFreshRead: true,
+                    },
+                    message: "Updated promo video",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("clear_promo_video", {
+        title: "Clear Promo Video",
+        description: "Wipe the promo video config for a variant so the user can start over. Does not delete the variant itself.",
+        inputSchema: {
+            projectId: z.string().uuid(),
+            variantId: z.string().uuid().optional(),
+        },
+    }, async (args) => {
+        try {
+            return ok(await client.clearPromoVideo(args), "Cleared promo video");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/build/tools/screenshots.js

@@ -0,0 +1,307 @@
+import { Buffer } from "node:buffer";
+import { z } from "zod";
+import { listPublicTemplateIds } from "../catalog.js";
+import { openUrl, fail, ok, startProgressHeartbeat } from "./utils.js";
+export function registerScreenshotTools(server, client) {
+    server.registerTool("prepare_screenshot_styles", {
+        title: "Prepare Personalized Screenshot Styles",
+        description: "Generate or reuse the project's personalized screenshot-style catalog before the user chooses a style. " +
+            "This prepares every screenshot template for phone, tablet, and desktop in one AI call and returns a catalogKey. " +
+            "Next call browse_templates with the returned templateIds, generationId, and catalogKey, then apply_screenshot_style with the selected templateId and catalogKey. " +
+            "Repeating this with the same app context and screenshot paths is a cache hit and does not regenerate AI content.",
+        inputSchema: {
+            generationId: z.string().uuid().describe("Project/generation UUID."),
+            selectedScreenshotPaths: z
+                .array(z.string().min(1))
+                .min(3)
+                .max(7)
+                .refine((paths) => new Set(paths).size === paths.length, {
+                message: "Screenshot paths must be unique",
+            })
+                .describe("3-7 unique project-relative paths from list_source_screenshots, in the desired story order."),
+            deviceType: z
+                .enum(["phone", "tablet", "desktop"])
+                .optional()
+                .describe("Initial preview device. All three device layouts are prepared regardless. Defaults to phone."),
+        },
+    }, async ({ generationId, selectedScreenshotPaths, deviceType = "phone" }, extra) => {
+        const stopHeartbeat = startProgressHeartbeat(extra, "Preparing personalized screenshot styles for every template…");
+        try {
+            const result = await client.generateLayouts({
+                generationId,
+                selectedScreenshotPaths,
+                deviceType,
+                previewAllTemplates: true,
+            });
+            const templateIds = listPublicTemplateIds(result.templatePayloads);
+            if (!result.catalogKey || templateIds.length === 0) {
+                throw new Error("The screenshot catalog response did not include a cache key and templates");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            result.cacheHit
+                                ? "Reused the existing personalized screenshot-style catalog."
+                                : "Prepared personalized screenshot styles for phone, tablet, and desktop.",
+                            `Catalog key: ${result.catalogKey}`,
+                            `Available template ids: ${templateIds.join(", ")}`,
+                            "Next: call browse_templates with these templateIds, generationId, and this catalog key so the gallery shows the personalized results; then apply_screenshot_style with the selected id.",
+                        ].join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        generationId,
+                        catalogKey: result.catalogKey,
+                        cacheHit: result.cacheHit === true,
+                        templateIds,
+                        devices: ["phone", "tablet", "desktop"],
+                        selectedScreenshotPaths,
+                    },
+                    message: result.cacheHit
+                        ? "Reused personalized screenshot styles"
+                        : "Prepared personalized screenshot styles",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+        finally {
+            stopHeartbeat();
+        }
+    });
+    server.registerTool("apply_screenshot_style", {
+        title: "Apply Personalized Screenshot Style",
+        description: "Create a new screenshot variant from a previously prepared personalized style catalog without another AI generation. " +
+            "Use only after prepare_screenshot_styles and browse_templates. The new variant includes phone, tablet, and desktop layouts and opens in the editor.",
+        inputSchema: {
+            generationId: z.string().uuid(),
+            catalogKey: z.string().min(1).max(128),
+            templateId: z.string().min(1),
+            deviceType: z
+                .enum(["phone", "tablet", "desktop"])
+                .optional()
+                .describe("Device to show first in the editor. Defaults to phone."),
+            paletteMode: z
+                .enum(["v1", "v2"])
+                .optional()
+                .describe("Color palette variant. v1 is the original palette; v2 uses stronger color separation. Defaults to v1."),
+        },
+    }, async ({ generationId, catalogKey, templateId, deviceType = "phone", paletteMode = "v1", }, extra) => {
+        try {
+            const result = await client.applyScreenshotTemplate({
+                generationId,
+                catalogKey,
+                templateId,
+                paletteMode,
+            });
+            const editorParams = new URLSearchParams({
+                projectId: generationId,
+                device: deviceType,
+                variantId: result.variantId,
+            });
+            if (result.detectedLanguage) {
+                editorParams.set("language", result.detectedLanguage);
+            }
+            const editorUrl = `${client.credentials.baseUrl}/editor?${editorParams.toString()}`;
+            await openUrl(server, editorUrl, "Opening the selected personalized screenshot style in the editor.", { signal: extra.signal });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Applied screenshot style ${templateId} without another AI generation.`,
+                            `Editor URL: ${editorUrl}`,
+                            "IMPORTANT: Paste this exact editor URL in the reply so the user can open it.",
+                        ].join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        generationId,
+                        variantId: result.variantId,
+                        templateId,
+                        editorUrl,
+                    },
+                    message: "Applied personalized screenshot style",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("generate_layouts", {
+        title: "Generate Layouts",
+        description: "Legacy direct generation for a single screenshot template. For the normal user-facing style chooser, prefer prepare_screenshot_styles → browse_templates → apply_screenshot_style so all personalized previews are generated once and the chosen style is applied from cache. " +
+            "Generate screenshot layouts for a project. " +
+            "For existing projects, pass generationId (same as projectId) — the API fetches screenshots from storage automatically. " +
+            "Do NOT pass screenshots when using generationId. " +
+            "Only pass metadata + screenshots (without generationId) for the ephemeral upload flow. " +
+            "Do NOT pass variantId — omit it so a new variant is always created. Never overwrite an existing variant. " +
+            "Do not use this tool for small edits to an existing layout; use transform_layout instead.",
+        inputSchema: {
+            generationId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("The project/generation UUID. When provided, the API loads screenshots from storage and saves results to DB. This is the primary way to call this tool for existing projects."),
+            projectId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Only needed for the upload flow (without generationId) to sign screenshot paths."),
+            metadata: z
+                .record(z.any())
+                .optional()
+                .describe("App metadata. Required only when generationId is NOT provided (upload flow)."),
+            screenshots: z
+                .array(z.object({
+                path: z.string().optional(),
+                url: z.string().optional(),
+                filename: z.string().optional(),
+            }))
+                .optional()
+                .describe("Screenshot list. Required only when generationId is NOT provided. Do NOT send when using generationId."),
+            templateId: z.string().optional(),
+            deviceType: z.enum(["phone", "tablet", "desktop"]).optional(),
+            variantId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("DO NOT pass this. Always omit so a new variant is created. Never overwrite existing variants."),
+        },
+    }, async (args, extra) => {
+        try {
+            const result = await client.generateLayouts(args);
+            const generationId = args.generationId || args.projectId || "";
+            const variantId = result.variantId || "";
+            const editorParams = new URLSearchParams({
+                projectId: generationId,
+                device: "phone",
+            });
+            if (variantId) {
+                editorParams.set("variantId", variantId);
+            }
+            if (result.detectedLanguage) {
+                editorParams.set("language", result.detectedLanguage);
+            }
+            const editorUrl = `${client.credentials.baseUrl}/editor?${editorParams.toString()}`;
+            await openUrl(server, editorUrl, "Opening the generated screenshot variant in the editor.", { signal: extra.signal });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "Generated layouts successfully.",
+                            `Editor URL: ${editorUrl}`,
+                            "IMPORTANT: Paste this exact editor URL in the reply so the user can open it.",
+                        ].join("\n"),
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: { ...result, editorUrl },
+                    message: "Generated layouts",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("list_source_screenshots", {
+        title: "List Template Source Screenshots",
+        description: "List all real source screenshots available to screenshot and social-graphics style generation, including project-relative path, signed preview URL, platform, and phone/tablet/desktop device type. No sample fallback is added. Use the returned paths to choose 3-7 inputs for prepare_screenshot_styles or prepare_social_graphics_styles.",
+        inputSchema: {
+            projectId: z.string().uuid(),
+        },
+    }, async ({ projectId }) => {
+        try {
+            const result = await client.listProjectScreenshots(projectId);
+            const screenshots = result.paths.map((path, index) => ({
+                path,
+                signedUrl: result.screenshotUrls[index],
+                platform: result.platforms[index],
+                deviceType: result.deviceTypes[index],
+            }));
+            return ok({
+                projectId,
+                defaultPlatform: result.defaultPlatform,
+                screenshots,
+            }, `Listed ${screenshots.length} template source screenshots`);
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("list_screenshots", {
+        title: "List Screenshots",
+        description: "List uploaded screenshot paths for a project",
+        inputSchema: {
+            projectId: z.string().uuid(),
+            deviceType: z.enum(["mobile", "tablet", "desktop"]).optional(),
+            platform: z.enum(["ios", "android"]).optional(),
+        },
+    }, async ({ projectId, deviceType, platform }) => {
+        try {
+            return ok(await client.listScreenshots({ projectId, deviceType, platform }), "Listed screenshots");
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("view_screenshot", {
+        title: "View Screenshot",
+        description: "Fetch a screenshot image and return it for visual analysis. " +
+            "Use this to inspect screenshots — extract colors, read UI text, understand layout context, or identify visual elements. " +
+            "Pass projectId and the relative path from list_screenshots or get_layout (e.g. 'mobile/ios/1234-image.PNG').",
+        inputSchema: {
+            projectId: z.string().uuid().describe("The project UUID."),
+            path: z
+                .string()
+                .describe("Relative screenshot path (e.g. 'mobile/ios/1234-IMG.PNG') from list_screenshots or the layout's screenshot.path field."),
+        },
+    }, async ({ projectId, path }) => {
+        try {
+            const fullPath = `${projectId}/${path}`;
+            const previewUrl = `${client.credentials.baseUrl}/api/preview?path=${encodeURIComponent(fullPath)}&w=320`;
+            const headers = new Headers();
+            headers.set("Authorization", `Bearer ${client.credentials.token}`);
+            const response = await fetch(previewUrl, { headers });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch image: ${response.status}`);
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            const mimeType = response.headers.get("content-type") || "image/png";
+            const base64 = Buffer.from(arrayBuffer).toString("base64");
+            return {
+                content: [
+                    {
+                        type: "image",
+                        data: base64,
+                        mimeType,
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    data: {
+                        projectId,
+                        path,
+                        mimeType,
+                        renderedAsImageContent: true,
+                    },
+                    message: "Fetched screenshot image",
+                },
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}