@cursor/bdk 0.2.14 → 0.2.16

package/dist/internal/convert-grokbot/convert.js

@@ -0,0 +1,470 @@
+/**
+ * Pure Grok Bot → BDK project mapping. Takes the recipe's bot and resolved
+ * answers; returns the project files as an in-memory tree plus a preview a
+ * client renders before confirming. No I/O and no clock: `generatedAt`
+ * comes from the caller.
+ */
+import { channelPostIdEntries } from "../../channels/slack/channel-watch.js";
+import { envPrefixFromName, slackEnvKeys } from "../../channels/slack/credentials.js";
+import { DEFAULT_MODEL } from "../../types.js";
+import { commentSafe } from "../comment-safe.js";
+import { isValidCron } from "../cron.js";
+import { CLI_COMMAND_NAME, PACKAGE_NAME } from "../distribution.js";
+import { serializeFrontmatter } from "../frontmatter.js";
+import { EVALS_CONFIG_TS, formatModelLiteral, GITIGNORE, JOURNAL_INSTRUCTIONS, MEMORY_TS, packageJson, SMOKE_EVAL_TS, tsconfig, } from "../init-scaffold.js";
+import { DEFAULT_MODEL_ID } from "../interview/agent-questions.js";
+import { mcpOauthSecretNames } from "../mcp-oauth.js";
+import { CANONICAL_PROJECT_ROOT, projectPath } from "../project-layout.js";
+import { SlugRegistry, slugFromDirectoryName } from "../slug.js";
+import { code, redactDeep, redactSecretValues } from "./checks.js";
+import { EXPORT_RECORD_PATH, handoffFiles, SLACK_PATH, } from "./handoff.js";
+import { fillInText, liveChannel, normalizeFillIn, triggerLabel, } from "./routine.js";
+import { emptySlackWiring, renderSlackChannel } from "./slack.js";
+export const EXPORT_RECORD_VERSION = 1;
+export const PREVIEW_VERSION = 1;
+export function convertGrokbot(input) {
+    const { answers, defaulted, ignored } = input.resolved;
+    const { bot, excluded } = selectBot(input.bot, answers);
+    const root = input.projectRoot ?? CANONICAL_PROJECT_ROOT;
+    const pluginSlugs = new Set(bot.plugins.map((plugin) => plugin.slug));
+    const out = {
+        root,
+        channels: new Set(answers.channels),
+        files: [],
+        from: new Map(),
+        preview: {
+            version: PREVIEW_VERSION,
+            name: answers.name,
+            answers,
+            defaulted,
+            ignored,
+            files: [],
+            excluded,
+            unmapped: bot.unknownFields.map((field) => ({
+                from: field,
+                reason: "Unknown recipe field; ignored.",
+            })),
+            fillIns: [],
+            secrets: { names: [], reauth: [] },
+            warnings: [],
+            setupSteps: [],
+        },
+        secrets: new Map(answers.secrets?.names?.map((name) => [name, {}])),
+        egress: new Set(),
+        reauth: new Set(answers.secrets?.reauth?.filter((slug) => pluginSlugs.has(slug))),
+        skillDirs: new SlugRegistry(),
+        scheduleNames: new SlugRegistry(),
+    };
+    for (const skill of bot.skills) {
+        out.skillDirs.claim(skill.slug);
+    }
+    if (bot.avatar !== undefined) {
+        out.preview.unmapped.push({
+            from: "profile.avatar",
+            reason: `BDK agents have no avatar; kept in ${EXPORT_RECORD_PATH} for the Slack app icon.`,
+        });
+    }
+    const directory = input.directoryName ?? answers.name;
+    const generator = `${PACKAGE_NAME}@${input.packageVersion}`;
+    emitSkills(bot, out);
+    const wiring = emitRoutines(bot, answers, out);
+    emitConnections(bot, answers, out);
+    const knowledge = emitMemory(bot, answers, out);
+    const slack = answers.slack === undefined
+        ? undefined
+        : emitSlackChannel(wiring, answers.slack, directory, out);
+    emitInstructions(bot, answers, out, wiring, knowledge);
+    emit(out, projectPath(root, "hooks/memory.ts"), MEMORY_TS, "scaffold");
+    emit(out, "evals/evals.config.ts", EVALS_CONFIG_TS, "scaffold");
+    emit(out, "evals/smoke.eval.ts", SMOKE_EVAL_TS, "scaffold");
+    emit(out, "package.json", packageJson({ name: directory, packageVersion: input.packageVersion }), "scaffold");
+    emit(out, "tsconfig.json", tsconfig(root), "scaffold");
+    emit(out, ".gitignore", GITIGNORE, "scaffold");
+    if (out.channels.has("github")) {
+        out.preview.setupSteps.push(`Add a GitHub channel under ${projectPath(root, "channels/")} (see the ${CLI_COMMAND_NAME} github skill).`);
+    }
+    if (out.channels.has("webhook")) {
+        out.preview.setupSteps.push(`Add a custom webhook channel under ${projectPath(root, "channels/")} and protect it with bearerAuth.`);
+    }
+    out.preview.secrets = { names: [...out.secrets.keys()].sort(), reauth: [...out.reauth].sort() };
+    emit(out, projectPath(root, "agent.ts"), renderAgentTs(bot, answers, out), "profile");
+    emit(out, EXPORT_RECORD_PATH, renderExportRecord({ input, generator, secrets: out.preview.secrets, slack }), "answers");
+    for (const file of handoffFiles({
+        root,
+        answers,
+        preview: out.preview,
+        secrets: out.secrets,
+        slug: slugFromDirectoryName(directory),
+        generator,
+        slack,
+    })) {
+        emit(out, file.path, file.contents, file.from);
+    }
+    const files = out.files.sort((a, b) => a.path.localeCompare(b.path));
+    out.preview.files = files.map((file) => ({
+        path: file.path,
+        from: out.from.get(file.path) ?? [],
+    }));
+    return { files, preview: redactDeep(out.preview) };
+}
+/** The items the answers keep, and the ones they leave out. */
+function selectBot(bot, answers) {
+    const excluded = [];
+    const keep = (kind, items) => {
+        const include = answers[kind]?.include;
+        const kept = items.filter((item) => include?.includes(item.slug) ?? true);
+        for (const item of items.filter((candidate) => !kept.includes(candidate))) {
+            excluded.push(`${kind}/${item.slug}`);
+        }
+        return kept;
+    };
+    const skills = keep("skills", bot.skills);
+    const routines = keep("routines", bot.routines);
+    const plugins = keep("plugins", bot.plugins);
+    const dropMemory = answers.memory === "drop" && bot.memory.length > 0;
+    if (dropMemory) {
+        excluded.push("memory");
+    }
+    return {
+        bot: {
+            ...bot,
+            skills,
+            routines,
+            plugins,
+            memory: dropMemory ? [] : bot.memory,
+            gettingStarted: skills.some((skill) => skill.slug === bot.gettingStarted)
+                ? bot.gettingStarted
+                : undefined,
+        },
+        excluded,
+    };
+}
+/** Secret-shaped values never reach a written file. */
+function emit(out, path, contents, ...from) {
+    const { text, redacted } = redactSecretValues(contents);
+    if (redacted > 0) {
+        out.preview.warnings.push(`${path}: removed ${redacted} value(s) that look like secrets. Store each with \`${CLI_COMMAND_NAME} secrets set\` and list its name in the answers (secrets.names).`);
+    }
+    out.files.push({ path, contents: text });
+    out.from.set(path, [...new Set(from)]);
+}
+function own(record, key) {
+    return record !== undefined && Object.hasOwn(record, key) ? record[key] : undefined;
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function skillFile(name, description, body) {
+    return `${serializeFrontmatter({ name, description: oneLine(description) })}${body.trim()}\n`;
+}
+function emitSchedule(out, slug, cron, body, from) {
+    const path = projectPath(out.root, `schedules/${out.scheduleNames.claim(slug)}.md`);
+    emit(out, path, `${serializeFrontmatter({ cron })}${body.trim()}\n`, from);
+    return path;
+}
+/** Schedules and Slack triggers are wired; GitHub and webhooks need a channel written by hand. */
+function planTrigger(trigger, out) {
+    const channel = liveChannel(trigger);
+    if (channel === undefined) {
+        return {
+            kind: "skip",
+            reason: trigger.kind === "cron"
+                ? `Paused schedule ${code(trigger.cron)}; add a file under ${projectPath(out.root, "schedules/")} to run it.`
+                : `${code(triggerLabel(trigger))} trigger has no BDK channel.`,
+        };
+    }
+    if (!out.channels.has(channel)) {
+        return {
+            kind: "skip",
+            reason: `${code(triggerLabel(trigger))} trigger dropped: the ${channel} channel is off.`,
+        };
+    }
+    if (trigger.kind === "cron" && !isValidCron(trigger.cron)) {
+        return { kind: "skip", reason: `${code(trigger.cron)} is not a five-field cron expression.` };
+    }
+    return trigger.kind === "github" || trigger.kind === "webhook"
+        ? { kind: "manual" }
+        : { kind: "wire" };
+}
+function emitSkills(bot, out) {
+    for (const skill of bot.skills) {
+        const from = `skills/${skill.slug}`;
+        emit(out, projectPath(out.root, `skills/${skill.slug}/SKILL.md`), skillFile(skill.name, skill.description, skill.body), from);
+        for (const trigger of skill.triggers) {
+            const plan = planTrigger(trigger, out);
+            if (plan.kind === "skip") {
+                out.preview.unmapped.push({ from: `${from}.trigger`, reason: plan.reason });
+            }
+            else {
+                emitSchedule(out, skill.slug, trigger.cron, `Use the \`${skill.slug}\` skill.`, from);
+            }
+        }
+    }
+}
+function emitRoutines(bot, answers, out) {
+    const slack = emptySlackWiring();
+    for (const routine of bot.routines) {
+        const from = `routines/${routine.slug}`;
+        const values = fillInValues(routine, answers);
+        const job = fillInText(routine.job, values);
+        recordFillIns(routine, values, job, out);
+        let wired = false;
+        const manual = [];
+        for (const trigger of routine.triggers) {
+            const plan = planTrigger(trigger, out);
+            if (plan.kind === "skip") {
+                out.preview.unmapped.push({ from, reason: plan.reason });
+            }
+            else if (plan.kind === "manual") {
+                manual.push(code(triggerLabel(trigger)));
+            }
+            else if (trigger.kind === "cron") {
+                wired = true;
+                const path = emitSchedule(out, routine.slug, trigger.cron, job, from);
+                if (routine.fillIns.some((fill) => fill.id === "timezone")) {
+                    out.preview.warnings.push(`${from}: BDK runs \`${trigger.cron}\` in UTC${values.timezone === undefined ? "" : `, not ${values.timezone}`}; adjust the cron in ${path} if the time matters.`);
+                }
+            }
+            else if (trigger.kind === "slack") {
+                wired = true;
+                wireSlack(slack, routine, trigger.match, values, job, from);
+            }
+        }
+        let skill;
+        if (!wired) {
+            skill = projectPath(out.root, `skills/${out.skillDirs.claim(routine.slug)}/SKILL.md`);
+            const description = fillInText(routine.description, values);
+            emit(out, skill, skillFile(routine.name, `${description} Not wired to a trigger yet; run it on request.`, job), from);
+        }
+        if (manual.length > 0) {
+            out.preview.setupSteps.push(`Wire ${code(from)}${skill === undefined ? "" : ` (${code(skill)})`} to ${manual.join(", ")}.`);
+        }
+    }
+    return slack;
+}
+function fillInValues(routine, answers) {
+    return Object.fromEntries(Object.entries(own(answers.fillIns, routine.slug) ?? {}).map(([id, value]) => [
+        id,
+        normalizeFillIn(id, value),
+    ]));
+}
+function recordFillIns(routine, values, job, out) {
+    for (const fill of routine.fillIns) {
+        out.preview.fillIns.push({
+            routine: routine.slug,
+            id: fill.id,
+            label: fill.label,
+            value: own(values, fill.id),
+        });
+    }
+    const unfilled = routine.fillIns.filter((fill) => own(values, fill.id) === undefined && job.includes(`{${fill.id}}`));
+    if (unfilled.length > 0) {
+        out.preview.warnings.push(`routines/${routine.slug}: placeholders ${unfilled.map((fill) => `{${fill.id}}`).join(", ")} are unfilled; set fillIns.${routine.slug} in the answers or edit the text.`);
+    }
+}
+function wireSlack(slack, routine, match, values, job, from) {
+    const channel = values.slack_channel;
+    const lead = {
+        mention: "when someone mentions you",
+        message: `new posts in ${channel ?? "a watched channel"}`,
+        keyword: `posts in ${channel ?? "a watched channel"} that mention "${values.slack_keyword ?? "{slack_keyword}"}"`,
+        reaction: `:${values.slack_emoji ?? "{slack_emoji}"}: reactions`,
+    }[match];
+    slack.sections.push({ title: `${routine.name} (${lead})`, body: job, from });
+    if (match === "mention") {
+        return;
+    }
+    if (match === "reaction") {
+        if (values.slack_emoji === undefined) {
+            slack.todos.push(`${routine.name}: set the reaction emoji (fillIns.${routine.slug}.slack_emoji).`);
+        }
+        else {
+            slack.emojis.push(values.slack_emoji);
+        }
+        return;
+    }
+    const [id] = channel === undefined ? [] : channelPostIdEntries([channel]);
+    if (id === undefined) {
+        slack.todos.push(`${routine.name}: add the watched channel's id (C…) to engagement.channelPosts.allow (fillIns.${routine.slug}.slack_channel${channel === undefined ? "" : ` is ${JSON.stringify(channel)}`}).`);
+    }
+    else {
+        slack.watch.push(id);
+    }
+    if (match === "message") {
+        slack.allPosts = true;
+    }
+    else if (values.slack_keyword === undefined) {
+        slack.todos.push(`${routine.name}: set the keyword (fillIns.${routine.slug}.slack_keyword).`);
+    }
+    else {
+        slack.keywords.push(values.slack_keyword.toLowerCase());
+    }
+}
+/** Names every shell reads the same inside single quotes; PowerShell also ends quotes at ‘’. */
+const PLAIN_NAME = /^[\p{L}\p{N} ._-]+$/u;
+function emitSlackChannel(wiring, answers, directoryName, out) {
+    const envPrefix = envPrefixFromName(directoryName);
+    const keys = slackEnvKeys(envPrefix);
+    const path = projectPath(out.root, "channels/slack.ts");
+    out.secrets.set(keys.bot, { file: path });
+    out.secrets.set(keys.app, { file: path });
+    const rendered = renderSlackChannel(wiring, envPrefix);
+    out.preview.warnings.push(...rendered.warnings);
+    emit(out, path, rendered.contents, ...(wiring.sections.length === 0
+        ? ["answers"]
+        : wiring.sections.map((section) => section.from)));
+    const named = PLAIN_NAME.test(answers.botName);
+    const create = named
+        ? `${CLI_COMMAND_NAME} slack create --dir . --name '${answers.botName}'`
+        : `${CLI_COMMAND_NAME} slack create --dir .`;
+    const naming = named ? "" : `; name it ${code(answers.botName)} in the wizard`;
+    out.preview.setupSteps.push(answers.app === "move"
+        ? `Slack: move the bot's existing Slack app and store its tokens in ${keys.bot} and ${keys.app} (see ${SLACK_PATH}).`
+        : `Slack: \`${create}\` mints the app and stores ${keys.bot} and ${keys.app}${naming} (see ${SLACK_PATH}).`);
+    return { answers, create, keys };
+}
+function emitConnections(bot, answers, out) {
+    for (const plugin of bot.plugins) {
+        const connector = own(answers.connectors, plugin.slug);
+        if (connector === undefined) {
+            throw new Error(`No connector answer for plugin "${plugin.slug}".`);
+        }
+        const path = projectPath(out.root, `mcp-connections/${plugin.slug}.ts`);
+        emit(out, path, [
+            `import { defineConnection } from "${PACKAGE_NAME}/connections";`,
+            "",
+            `// Grok Bot plugin "${commentSafe(plugin.name)}".`,
+            ...connectionBody(plugin, connector),
+            "",
+        ].join("\n"), `plugins/${plugin.slug}`);
+        if (connector.auth === "cursor-account") {
+            continue;
+        }
+        out.egress.add(new URL(connector.url).hostname);
+        if (connector.auth === "secret") {
+            out.secrets.set(connector.secret, { file: path });
+            continue;
+        }
+        const names = mcpOauthSecretNames(plugin.slug);
+        for (const name of [names.accessToken, names.refreshToken, names.clientId]) {
+            out.secrets.set(name, { file: path, oauth: true });
+        }
+        out.reauth.add(plugin.slug);
+    }
+}
+function connectionBody(plugin, connector) {
+    switch (connector.auth) {
+        case "cursor-account":
+            return [
+                "// Tools run on the Cursor backend with your account's stored credentials,",
+                "// so no token lives in this project. Authorize the connector in Cursor",
+                "// (dashboard -> MCP) for the account this agent runs as.",
+                "export default defineConnection({",
+                "  cursorAccount: true,",
+                `  servers: [${JSON.stringify(connector.server)}],`,
+                "});",
+            ];
+        case "oauth":
+            return [
+                `// Sign in with \`${CLI_COMMAND_NAME} mcp oauth ${plugin.slug}\` (add --store for a hosted deploy).`,
+                "export default defineConnection({",
+                `  url: ${JSON.stringify(connector.url)},`,
+                "  oauth: true,",
+                "});",
+            ];
+        case "secret":
+            return [
+                `// \${${connector.secret}} expands from the environment when a client opens.`,
+                "export default defineConnection({",
+                `  url: ${JSON.stringify(connector.url)},`,
+                `  headers: { authorization: "Bearer \${${connector.secret}}" },`,
+                "});",
+            ];
+    }
+}
+function emitMemory(bot, answers, out) {
+    if (bot.memory.length === 0) {
+        return undefined;
+    }
+    if (answers.memory === "kv") {
+        const path = projectPath(out.root, "lib/memory-seed.json");
+        emit(out, path, `${JSON.stringify(bot.memory, null, 2)}\n`, "memory");
+        out.preview.warnings.push(`memory: BDK has no built-in KV seed. The memories are data in ${path}; load them into ctx.host.kv from your own code, or re-export with memory "skill".`);
+        return undefined;
+    }
+    const slug = out.skillDirs.claim("knowledge");
+    emit(out, projectPath(out.root, `skills/${slug}/SKILL.md`), skillFile("knowledge", `What ${bot.name} already knows about its user and team, carried over from its Grok Bot memory. Read it before answering questions about people, preferences, or past decisions.`, knowledgeBody(bot.memory)), "memory");
+    return slug;
+}
+function knowledgeBody(memory) {
+    const groups = [
+        ["Profile", memory.filter((row) => row.kind === "profile")],
+        ["Log", memory.filter((row) => row.kind === "log")],
+        ["Notes", memory.filter((row) => row.kind !== "profile" && row.kind !== "log")],
+    ];
+    return groups
+        .filter(([, rows]) => rows.length > 0)
+        .map(([title, rows]) => `## ${title}\n\n${rows
+        .map((row) => `- ${row.createdAt === undefined ? "" : `${row.createdAt.slice(0, 10)}: `}${row.content}`)
+        .join("\n")}`)
+        .join("\n\n");
+}
+function emitInstructions(bot, answers, out, slack, knowledge) {
+    const sections = [`# ${bot.name}`, answers.description];
+    const from = ["profile"];
+    if (bot.gettingStarted !== undefined) {
+        sections.push(`## Getting started\n\nWhen someone talks to you for the first time, start with the \`${bot.gettingStarted}\` skill.`);
+        from.push("gettingStarted");
+    }
+    if (slack.sections.length > 0) {
+        sections.push([
+            "## Slack",
+            ...slack.sections.map((section) => `### ${section.title}\n\n${section.body}`),
+        ].join("\n\n"));
+        from.push(...slack.sections.map((section) => section.from));
+    }
+    if (knowledge !== undefined) {
+        sections.push(`## What you know\n\nWhat you already know about your user and team is in the \`${knowledge}\` skill. Read it before answering questions about people, preferences, or past decisions.`);
+        from.push("memory");
+    }
+    sections.push(JOURNAL_INSTRUCTIONS.trim());
+    emit(out, projectPath(out.root, "instructions.md"), `${sections.join("\n\n")}\n`, ...from);
+}
+function renderAgentTs(bot, answers, out) {
+    const model = formatModelLiteral(answers.model === DEFAULT_MODEL_ID ? DEFAULT_MODEL : answers.model);
+    const lines = [
+        `import { defineAgent } from "${PACKAGE_NAME}";`,
+        "",
+        "export default defineAgent({",
+        `  name: ${JSON.stringify(bot.name)},`,
+        `  description: ${JSON.stringify(oneLine(answers.description))},`,
+        `  model: ${model},`,
+    ];
+    const secretNames = [...out.secrets.keys()].sort();
+    const egress = [...out.egress].sort();
+    if (secretNames.length > 0 || egress.length > 0) {
+        lines.push("  hosting: {");
+        if (secretNames.length > 0) {
+            lines.push(`    secretNames: [${secretNames.map((name) => JSON.stringify(name)).join(", ")}],`);
+        }
+        if (egress.length > 0) {
+            lines.push(`    egressDomains: [${egress.map((host) => JSON.stringify(host)).join(", ")}],`);
+        }
+        lines.push("  },");
+    }
+    lines.push("});", "");
+    return lines.join("\n");
+}
+function renderExportRecord(args) {
+    const { input, slack } = args;
+    const record = {
+        version: EXPORT_RECORD_VERSION,
+        generatedAt: input.generatedAt,
+        generator: args.generator,
+        recipe: { name: input.bot.name, avatar: input.bot.avatar },
+        secrets: args.secrets,
+        slackTokens: slack === undefined ? null : [slack.keys.bot, slack.keys.app],
+        answers: input.resolved.answers,
+    };
+    return `${JSON.stringify(record, null, 2)}\n`;
+}

package/dist/internal/convert-grokbot/handoff.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The files that carry an export's follow-up work: SECRETS.md, SLACK.md
+ * (app plan, review justification, scopes), a finish-the-export skill, an
+ * AGENTS.md that points at all three, and a Cloud Agent environment. Coding
+ * agents read these as instructions, so they name the project by its
+ * validated slug and keep recipe text to single quoted lines.
+ */
+import type { ProjectRoot } from "../project-layout.js";
+import type { ResolvedAnswers, ResolvedSlack } from "./answers.js";
+import type { GrokbotPreview, Source } from "./convert.js";
+export declare const EXPORT_RECORD_PATH = "grokbot-export.json";
+export declare const SECRETS_PATH = "SECRETS.md";
+export declare const SLACK_PATH = "SLACK.md";
+export declare const FINISH_SKILL_PATH = ".cursor/skills/finish-grokbot-export/SKILL.md";
+/** Where a secret is read: a project file, OAuth for a connection, or only the answers. */
+export interface SecretUse {
+    file?: string;
+    oauth?: boolean;
+}
+export interface SlackApp {
+    answers: ResolvedSlack;
+    /** The `slack create` command that mints a new app. */
+    create: string;
+    keys: {
+        bot: string;
+        app: string;
+    };
+}
+export interface HandoffInput {
+    root: ProjectRoot;
+    answers: ResolvedAnswers;
+    preview: GrokbotPreview;
+    secrets: ReadonlyMap<string, SecretUse>;
+    /** Deploy slug, when the directory name makes a valid one. */
+    slug?: string;
+    generator: string;
+    slack?: SlackApp;
+}
+export declare function handoffFiles(input: HandoffInput): Array<{
+    path: string;
+    contents: string;
+    from: Source;
+}>;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/internal/convert-grokbot/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../../src/internal/convert-grokbot/handoff.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3D,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AACxD,eAAO,MAAM,YAAY,eAAe,CAAC;AACzC,eAAO,MAAM,UAAU,aAAa,CAAC;AACrC,eAAO,MAAM,iBAAiB,kDAAkD,CAAC;AAEjF,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACxC,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,YAAY,GAClB,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAezD"}

package/dist/internal/convert-grokbot/handoff.js

@@ -0,0 +1,160 @@
+/**
+ * The files that carry an export's follow-up work: SECRETS.md, SLACK.md
+ * (app plan, review justification, scopes), a finish-the-export skill, an
+ * AGENTS.md that points at all three, and a Cloud Agent environment. Coding
+ * agents read these as instructions, so they name the project by its
+ * validated slug and keep recipe text to single quoted lines.
+ */
+import { buildSlackManifest } from "../../channels/slack/manifest.js";
+import { CLI_COMMAND_NAME as CLI } from "../distribution.js";
+import { serializeFrontmatter } from "../frontmatter.js";
+import { agentsMd } from "../init-scaffold.js";
+import { code, singleLine } from "./checks.js";
+export const EXPORT_RECORD_PATH = "grokbot-export.json";
+export const SECRETS_PATH = "SECRETS.md";
+export const SLACK_PATH = "SLACK.md";
+export const FINISH_SKILL_PATH = ".cursor/skills/finish-grokbot-export/SKILL.md";
+export function handoffFiles(input) {
+    const files = [
+        { path: SECRETS_PATH, contents: secretsMd(input), from: "answers" },
+        { path: FINISH_SKILL_PATH, contents: finishSkill(input), from: "answers" },
+        { path: "AGENTS.md", contents: agentsMdWithExport(input), from: "scaffold" },
+        {
+            path: ".cursor/environment.json",
+            contents: `${JSON.stringify({ name: input.answers.name, install: "npm install" }, null, 2)}\n`,
+            from: "scaffold",
+        },
+    ];
+    if (input.slack !== undefined) {
+        files.push({ path: SLACK_PATH, contents: slackMd(input.slack), from: "answers" });
+    }
+    return files;
+}
+function secretUse(use) {
+    if (use.file === undefined) {
+        return "your own code (named in the answers)";
+    }
+    return use.oauth === true
+        ? `OAuth for ${code(use.file)} (written by \`${CLI} mcp oauth\`)`
+        : code(use.file);
+}
+function secretsMd(input) {
+    const lines = [
+        "# Secrets",
+        "",
+        "The project reads these secrets by name. The Grok Bot recipe carried no values, so set each one before you run the agent.",
+        "",
+    ];
+    if (input.secrets.size === 0) {
+        lines.push("None yet.");
+    }
+    else {
+        lines.push("| Name | Read by |", "| --- | --- |");
+        for (const [name, use] of [...input.secrets].sort(([a], [b]) => a.localeCompare(b))) {
+            lines.push(`| \`${name}\` | ${secretUse(use)} |`);
+        }
+    }
+    lines.push("", `Local runs read secrets from the environment. A deployment reads the values you store with \`${CLI} secrets set ${input.slug ?? "<slug>"} NAME...\`.`);
+    const reauth = input.preview.secrets.reauth;
+    if (reauth.length > 0) {
+        lines.push("", "## Fresh sign-ins", "", "These connectors need a new sign-in; tokens never move with an export.", "", ...reauth.map((slug) => `- \`${slug}\`: \`${CLI} mcp oauth ${slug}\` for an OAuth connector (add \`--store\` for a deployment), or reconnect it in your Cursor account.`));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function cutoverLine(slack) {
+    switch (slack.cutover) {
+        case "manual":
+            return "switch Slack traffic to this agent by hand once it works.";
+        case "after-deploy":
+            return "switch Slack traffic to this agent after its first deploy.";
+        case "scheduled":
+            return `switch Slack traffic to this agent at ${slack.cutoverAt}.`;
+    }
+}
+function slackMd({ answers, create, keys }) {
+    const prefix = answers.teamPrefix === undefined ? "" : ` (team prefix ${code(answers.teamPrefix)})`;
+    const lines = [
+        "# Slack app",
+        "",
+        answers.app === "move"
+            ? `- App: move the Grok Bot's existing Slack app. Put its bot token in \`${keys.bot}\` and its app-level token in \`${keys.app}\`.`
+            : `- App: mint a new one with ${code(create)}.`,
+        `- Bot name: ${code(answers.botName)}${prefix}`,
+        `- Cutover: ${cutoverLine(answers)}`,
+        "",
+        "## Security justification",
+        "",
+        "Paste this into the Slack app approval request.",
+        "",
+        ...answers.justification.split(/\r\n?|\n/).map((line) => `> ${line}`.trimEnd()),
+        "",
+        "## Scopes",
+        "",
+        "The app requests these bot scopes:",
+        "",
+        ...buildSlackManifest({ name: answers.botName, env: "prod" }).oauth_config.scopes.bot.map((scope) => `- \`${scope}\``),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function deployLine(deploy) {
+    const command = `\`${CLI} deploy\``;
+    switch (deploy.when) {
+        case "after-review":
+            return `Deploy with ${command} once the steps above check out.`;
+        case "now":
+            return `Deploy with ${command} as soon as the steps above are done.`;
+        case "scheduled":
+            return `Deploy with ${command} at ${deploy.at}.`;
+        case "never":
+            return "No deploy is planned; keep the agent local.";
+    }
+}
+function finishSkill(input) {
+    const { answers, preview } = input;
+    const repo = answers.repo.namespace === undefined
+        ? answers.repo.name
+        : `${answers.repo.namespace}/${answers.repo.name}`;
+    const steps = [
+        `Set the secrets in \`${SECRETS_PATH}\`.`,
+        ...preview.setupSteps,
+        `Run \`${CLI} validate\`, then \`${CLI} dev\`, and try the agent in the playground.`,
+        `Push the project to a \`${repo}\` repository; the export does not create it.`,
+        deployLine(answers.deploy),
+    ];
+    const lines = [
+        `# Finish the ${answers.name} export`,
+        "",
+        `${input.generator} generated this project from a Grok Bot recipe. \`${EXPORT_RECORD_PATH}\` records the recipe and every answer.`,
+        "",
+        ...steps.map((step, index) => `${index + 1}. ${singleLine(step)}`),
+    ];
+    const leftBehind = [
+        ...preview.excluded.map((from) => `- ${code(from)}: left out by the answers.`),
+        ...preview.unmapped.map((entry) => `- ${code(entry.from)}: ${singleLine(entry.reason)}`),
+    ];
+    if (leftBehind.length > 0) {
+        lines.push("", "## Not carried over", "", ...leftBehind);
+    }
+    if (preview.warnings.length > 0) {
+        lines.push("", "## Review before deploying", "", ...preview.warnings.map((warning) => `- ${singleLine(warning)}`));
+    }
+    const frontmatter = serializeFrontmatter({
+        name: "finish-grokbot-export",
+        description: `Finish moving ${answers.name} off Grok Bot: secrets, connector sign-ins, the Slack app, and deploy. Use when asked to finish, deploy, or cut over this exported agent.`,
+    });
+    return `${frontmatter}${lines.join("\n")}\n`;
+}
+function agentsMdWithExport(input) {
+    const files = [
+        `\`${EXPORT_RECORD_PATH}\` records the recipe and every answer`,
+        `\`${SECRETS_PATH}\` lists the secrets it reads`,
+    ];
+    if (input.slack !== undefined) {
+        files.push(`\`${SLACK_PATH}\` holds the Slack app plan and review text`);
+    }
+    return `${agentsMd(input.answers.name, input.root)}
+## Exported from Grok Bot
+
+This project came from a Grok Bot recipe. ${files.join(", ")}, and \`${FINISH_SKILL_PATH}\` lists what is left to do.
+`;
+}