@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/channels/slack/setup-server.js

@@ -1,246 +0,0 @@
-import { randomBytes } from "node:crypto";
-import { createServer } from "node:http";
-import { field, formCard, openButton, privacy, prose, refusal, sendPage, setupRequestUrl, statusCard, step, submit, } from "../../setup-page.js";
-/** Where Slack's App Configuration tokens are generated: the page names the section, and links to the page it is on. */
-const SLACK_APPS_URL = "https://api.slack.com/apps";
-const TITLE = "Connect Slack — FastAgent";
-function tokensForm(error) {
-    return {
-        title: TITLE,
-        card: formCard("Connect Slack", [
-            step(1, "Generate two tokens in Slack", prose("Under <b>Your App Configuration Tokens</b>, choose <b>Generate Token</b> for your workspace.") +
-                openButton("Open Slack", SLACK_APPS_URL)),
-            step(2, "Paste them here", (error ? refusal("Those tokens were not accepted.", ` ${error}`) : "") +
-                field({
-                    id: "access",
-                    label: "Access Token",
-                    placeholder: "xoxe.xoxp-…",
-                    secret: true,
-                    invalid: error !== undefined,
-                    autofocus: error !== undefined,
-                }) +
-                field({
-                    id: "refresh",
-                    label: "Refresh Token",
-                    placeholder: "xoxe-…",
-                    secret: true,
-                    invalid: error !== undefined,
-                }) +
-                submit("Create Slack app") +
-                privacy(), { bare: error === undefined }),
-        ].join("")),
-    };
-}
-/** A page that says where the setup stands. */
-const status = (input, title = "FastAgent setup") => ({
-    title,
-    card: statusCard(input),
-});
-/** Temporary onboarding-only responder. */
-export async function startSlackSetupServer() {
-    const nonce = randomBytes(24).toString("hex");
-    const requestPath = `/slack/setup/${nonce}`;
-    const redirectPath = `/slack/oauth/${nonce}`;
-    const tokensPath = `/slack/tokens/${nonce}`;
-    const nextPath = `/slack/next/${nonce}`;
-    let takeTokens;
-    let pasted = false;
-    let after;
-    let lastShown;
-    /** The last page a browser waiting after the pair sees, and when it has seen it (bounded by one refresh window). */
-    const lastPage = (said, failed) => {
-        if (!pasted || after !== undefined)
-            return Promise.resolve();
-        after = { said, failed };
-        return new Promise((resolve) => {
-            const timer = setTimeout(resolve, 5_000);
-            lastShown = () => {
-                clearTimeout(timer);
-                resolve();
-            };
-        });
-    };
-    let settleOAuth;
-    const oauth = new Promise((resolve) => {
-        settleOAuth = resolve;
-    });
-    const server = createServer((request, response) => {
-        const url = setupRequestUrl(request, response);
-        if (url === undefined)
-            return;
-        if (request.method === "GET" && url.pathname === "/health") {
-            response.end("ok\n");
-            return;
-        }
-        if (request.method === "GET" && url.pathname === redirectPath) {
-            const callback = {
-                code: url.searchParams.get("code") ?? undefined,
-                state: url.searchParams.get("state") ?? undefined,
-                error: url.searchParams.get("error") ?? undefined,
-            };
-            settleOAuth?.(callback);
-            settleOAuth = undefined;
-            // The onboarding flow still has to validate state and exchange the code.
-            sendPage(response, 200, status(callback.error !== undefined
-                ? {
-                    state: "failed",
-                    heading: "Slack authorization was not approved",
-                    lede: callback.error
-                        ? `OAuth error: ${callback.error}`
-                        : "The callback reported an authorization error.",
-                    next: "Go back to your coding agent to restart setup.",
-                }
-                : {
-                    state: "working",
-                    heading: "OAuth response received",
-                    lede: "FastAgent still needs to verify this response and finish the installation.",
-                    next: "Go back to your coding agent to check the result. You can close this tab.",
-                }));
-            return;
-        }
-        if (url.pathname === tokensPath && (request.method === "GET" || request.method === "POST")) {
-            if (takeTokens === undefined) {
-                // Taken already, or not asked for: the page is one-time.
-                sendPage(response, 404, status({ state: "failed", heading: "This page is no longer in use", next: "Go back to your coding agent." }));
-                return;
-            }
-            if (request.method === "GET") {
-                sendPage(response, 200, tokensForm());
-                return;
-            }
-            readBody(request, (body) => {
-                if (body === undefined) {
-                    response.statusCode = 413;
-                    response.end("payload too large\n");
-                    return;
-                }
-                const form = new URLSearchParams(body);
-                try {
-                    takeTokens?.({ access: (form.get("access") ?? "").trim(), refresh: (form.get("refresh") ?? "").trim() });
-                }
-                catch (error) {
-                    sendPage(response, 200, tokensForm(error.message));
-                    return;
-                }
-                response.statusCode = 303;
-                response.setHeader("location", nextPath);
-                response.end();
-            });
-            return;
-        }
-        if (request.method === "GET" && url.pathname === nextPath) {
-            if (after === undefined) {
-                // Says what comes next, so the redirect to Slack's page is no surprise.
-                sendPage(response, 200, {
-                    ...status({
-                        state: "working",
-                        heading: "Creating your Slack app",
-                        lede: "In a moment Slack will ask you to click Allow.",
-                    }),
-                    head: '<meta http-equiv="refresh" content="2">',
-                });
-            }
-            else if ("url" in after) {
-                response.statusCode = 303;
-                response.setHeader("location", after.url);
-                response.end();
-            }
-            else {
-                sendPage(response, 200, status({
-                    state: after.failed ? "failed" : "done",
-                    heading: after.failed ? "Setup stopped" : "Done",
-                    lede: after.said,
-                    next: "Go back to your coding agent.",
-                }));
-                lastShown?.();
-            }
-            return;
-        }
-        if (request.method === "POST" && url.pathname === requestPath) {
-            readBody(request, (body) => {
-                if (body === undefined) {
-                    response.statusCode = 413;
-                    response.end("payload too large\n");
-                    return;
-                }
-                try {
-                    const payload = JSON.parse(body);
-                    if (payload.type === "url_verification" && typeof payload.challenge === "string") {
-                        response.setHeader("content-type", "application/json");
-                        response.end(JSON.stringify({ challenge: payload.challenge }));
-                        return;
-                    }
-                }
-                catch {
-                    // Fall through: setup never acknowledges normal events or malformed traffic.
-                }
-                response.statusCode = 404;
-                response.end("not found\n");
-            });
-            return;
-        }
-        response.statusCode = 404;
-        response.end("not found\n");
-    });
-    await new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(0, "127.0.0.1", () => {
-            server.off("error", reject);
-            resolve();
-        });
-    });
-    const address = server.address();
-    if (!address || typeof address === "string") {
-        server.close();
-        throw new Error("Slack setup server did not receive a local TCP port");
-    }
-    return {
-        port: address.port,
-        requestPath,
-        redirectPath,
-        tokensPath,
-        waitForTokens: (check) => new Promise((resolve) => {
-            takeTokens = (pair) => {
-                const taken = check(pair);
-                takeTokens = undefined;
-                pasted = true;
-                resolve(taken);
-            };
-        }),
-        next(url) {
-            after = { url };
-        },
-        failed: (message) => lastPage(message, true),
-        done: (message) => lastPage(message, false),
-        async waitForOAuth(timeoutMs = 10 * 60_000) {
-            let timer;
-            const timeout = new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error("Slack OAuth timed out — re-run `fastagent add slack`")), timeoutMs);
-                timer.unref();
-            });
-            try {
-                return await Promise.race([oauth, timeout]);
-            }
-            finally {
-                if (timer)
-                    clearTimeout(timer);
-            }
-        },
-        close: () => new Promise((resolve, reject) => {
-            server.close((error) => (error ? reject(error) : resolve()));
-        }),
-    };
-}
-/** A request's body, or `undefined` past 64 KB: setup traffic is small, and anything larger is not ours. */
-function readBody(request, then) {
-    let body = "";
-    let tooLarge = false;
-    request.on("data", (chunk) => {
-        if (tooLarge)
-            return;
-        body += String(chunk);
-        if (Buffer.byteLength(body) > 64 * 1024)
-            tooLarge = true;
-    });
-    request.on("end", () => then(tooLarge ? undefined : body));
-}

package/dist/cli/add-feishu.d.ts

@@ -1,41 +0,0 @@
-import { type FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
-import { type FeishuApi } from "../channels/feishu/feishu-api.ts";
-import type { DeclaredChannel } from "../channels/discover.ts";
-import { type Person } from "./person.ts";
-export interface AgentScopeCheck {
-    /** Safe to proceed to version publishing now; false means Permissions still needs console or admin work. */
-    publishReady: boolean;
-    /** The scopes found missing; empty when the list could not be read (`publishReady` is false then). */
-    missing: string[];
-}
-/**
- * Check that the app holds what an app of this ingress needs ({@link feishuAppScopes}). A created app asks for them on
- * its confirm page, and a tenant may still withhold some (its approval policy, or an app made by hand): those are
- * NAMED, with what each one costs, and the console page that requests them is opened pre-filled. Nothing is requested
- * through the config API — that needs a scope of its own, which a tenant can withhold just the same.
- */
-export declare function checkAgentScopes(input: {
-    kind: "feishu" | "lark";
-    appId: string;
-    apiBase: string;
-    ingress: FeishuSubscriptionMode;
-    api: Pick<FeishuApi, "listAppScopes">;
-    note?: (message: string) => void;
-    /** Who is sent to the console page that requests a missing permission. */
-    person?: Person;
-}): Promise<AgentScopeCheck>;
-/** Create or resume the platform app behind `add feishu` / `add lark`. */
-export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", ingress: FeishuSubscriptionMode, 
-/** The command that continues an interrupted setup: the one that started it. */
-rerun?: string, 
-/** Who takes the steps only a person can: at this terminal, or a coding agent's person through a ticket. */
-person?: Person): Promise<Record<string, string> | undefined>;
-export declare function feishuAppSecretNames(kind: "feishu" | "lark", ingress: FeishuSubscriptionMode): string[];
-interface FeishuAppSetup {
-    kind: "feishu" | "lark";
-    ingress: FeishuSubscriptionMode;
-}
-export declare function unpreparedFeishuApps(channels: readonly DeclaredChannel[], values: ReadonlyMap<string, string>): FeishuAppSetup[];
-export declare function assertIndependentFeishuApps(agentDir: string, kinds: readonly ("feishu" | "lark")[], values: ReadonlyMap<string, string>): void;
-export declare function prepareFeishuApps(agentDir: string, apps: readonly FeishuAppSetup[], rerun: string, person: Person, onboard?: typeof onboardFeishuCloudApp): Promise<void>;
-export {};

package/dist/cli/add-feishu.js

@@ -1,391 +0,0 @@
-/**
- * `fastagent add feishu|lark` app onboarding — the cloud-facing half of runAdd, kept out of cli.ts (which
- * self-executes on import), mirroring models-view.ts/auth-view.ts.
- */
-import { readFile } from "node:fs/promises";
-import { isCancel, log as clackLog, password, text as clackText } from "@clack/prompts";
-import { bootstrapFeishuVerificationToken } from "../channels/feishu/bootstrap-token.js";
-import { FEISHU_APP_CONFIG_SCOPE, feishuAppAddons, feishuAppScopes, feishuScopeRequestUrl, scopeSatisfied, } from "../channels/feishu/setup-mode.js";
-import { cloudFor } from "../channels/feishu/cloud.js";
-import { createFeishuApi, isFeishuConfigApiMissing, isFeishuCredentialsRefused, isTransientFeishuRegistrationError, } from "../channels/feishu/feishu-api.js";
-import { registerFeishuApp } from "../channels/feishu/register-app.js";
-import { LarkCredentialsRefused, startLarkCredentialsPage, startLarkVerificationPage, } from "../channels/lark/credentials-page.js";
-import { onboardLarkApp } from "../channels/lark/onboard.js";
-import { dotEnvPath, loadEnvValues, parseEnvContent } from "../value-file.js";
-import { openExternalUrl } from "../open-url.js";
-import { terminalPerson } from "./person.js";
-import { AGENT_ENVIRONMENT_ENV } from "../paths.js";
-import { appendChannelDotEnv } from "../scaffold/add-channel.js";
-import { startCloudflareTunnel } from "../tunnel.js";
-/**
- * Check that the app holds what an app of this ingress needs ({@link feishuAppScopes}). A created app asks for them on
- * its confirm page, and a tenant may still withhold some (its approval policy, or an app made by hand): those are
- * NAMED, with what each one costs, and the console page that requests them is opened pre-filled. Nothing is requested
- * through the config API — that needs a scope of its own, which a tenant can withhold just the same.
- */
-export async function checkAgentScopes(input) {
-    const { kind, appId, apiBase, api } = input;
-    const note = input.note ?? ((message) => console.error(message));
-    const person = input.person ?? terminalPerson;
-    const needed = feishuAppScopes(input.ingress);
-    const requested = needed.map((entry) => entry.request);
-    let scopes;
-    try {
-        scopes = await api.listAppScopes();
-    }
-    catch (error) {
-        const url = feishuScopeRequestUrl(apiBase, appId, requested);
-        note(`[fastagent] warn: could not read the ${kind} app's permissions: ${String(error)}`);
-        person.afterwards(`make sure the ${kind} app holds ${requested.join(", ")} before publishing`, url);
-        return { publishReady: false, missing: [] };
-    }
-    // A user-type entry is not the tenant scope the app acts with.
-    const tenant = scopes.filter((scope) => scope.type === undefined || scope.type === "tenant");
-    const granted = (name) => tenant.some((scope) => scope.name === name && scope.grantStatus === 1);
-    const missing = needed.filter((entry) => !scopeSatisfied(entry, granted));
-    if (missing.length === 0) {
-        note(`[fastagent] ${kind} app permissions: ${requested.join(", ")} granted`);
-        return { publishReady: true, missing: [] };
-    }
-    // "Not granted", not "not requested": the list omits a scope still under review (measured), so the two look alike.
-    const describe = (entry) => `\n  ${entry.request}: without it ${entry.withoutIt}`;
-    const url = feishuScopeRequestUrl(apiBase, appId, missing.map((entry) => entry.request));
-    person.afterwards(`the ${kind} app is not granted:${missing.map(describe).join("")}\n` +
-        `Tick and enable them on that page (one may already be awaiting a tenant admin's approval), before publishing`, url);
-    return { publishReady: false, missing: missing.map((entry) => entry.request) };
-}
-/** Create or resume the platform app behind `add feishu` / `add lark`. */
-export async function onboardFeishuCloudApp(target, kind, ingress, 
-/** The command that continues an interrupted setup: the one that started it. */
-rerun = `fastagent add ${kind}${ingress === "webhook" ? " --ingress webhook" : ""}`, 
-/** Who takes the steps only a person can: at this terminal, or a coding agent's person through a ticket. */
-person = terminalPerson) {
-    const env = dotEnvPath(target); // the file actually written — never the default spelling
-    const { envPrefix, apiBase, capabilities } = cloudFor(kind);
-    const requiredNames = feishuAppSecretNames(kind, ingress);
-    const existing = await activeDotEnvValues(target, requiredNames);
-    if (process.env[AGENT_ENVIRONMENT_ENV] === "production") {
-        assertIndependentFeishuApps(target, [kind], new Map(Object.entries(existing)));
-    }
-    if (Object.keys(existing).length === requiredNames.length) {
-        console.error(`[fastagent] ${requiredNames.join("/")} already set in ${env} — keeping them`);
-        // WebSocket still needs its console mode/publish guidance.
-        if (ingress === "webhook") {
-            const appId = existing[`${envPrefix}_APP_ID`];
-            const appSecret = existing[`${envPrefix}_APP_SECRET`];
-            await checkAgentScopes({
-                kind,
-                appId,
-                apiBase,
-                ingress,
-                api: createFeishuApi({ kind, baseUrl: apiBase, appId, appSecret }),
-                person,
-            });
-            return undefined;
-        }
-    }
-    if (capabilities.appCreation === "scan-to-create") {
-        await createFeishuAppFlow(target, existing, ingress, rerun, person);
-        return undefined;
-    }
-    // guided-console (lark): the intl cloud cannot complete the bound device flow — collect + validate.
-    const credentials = await onboardLarkApp(person === terminalPerson ? larkAtTerminal : larkThrough(person, target), {
-        existing,
-        ingress,
-        rerun,
-        verifyCredentials: async (appId, appSecret) => {
-            if (process.env[AGENT_ENVIRONMENT_ENV] === "production") {
-                assertIndependentFeishuApps(target, ["lark"], new Map([["LARK_APP_ID", appId]]));
-            }
-            await createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret }).verifyCredentials();
-            console.error(`[fastagent] Lark App ID / Secret verified`);
-        },
-        // The same boundary `add feishu` keeps: a pair given just now is written before any step that can fail, so a
-        // rerun finds it and carries on, instead of asking for it again.
-        keep: async (appId, appSecret) => {
-            const kept = {
-                LARK_APP_ID: appId,
-                LARK_APP_SECRET: appSecret,
-                ...(ingress === "webhook" ? { LARK_VERIFICATION_TOKEN: "" } : {}),
-            };
-            await appendChannelDotEnv(target, "lark", kept, Object.keys(kept), ingress);
-            console.error(`[fastagent] wrote LARK_APP_ID, LARK_APP_SECRET to ${env}`);
-        },
-        bootstrapWebhook: async (appId, appSecret) => {
-            const api = createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret });
-            console.error(`[fastagent] trying Lark's webhook-mode + Verification-Token bootstrap (temporary tunnel)…`);
-            try {
-                const token = await bootstrapFeishuVerificationToken({
-                    api,
-                    appId,
-                    kind: "lark",
-                    startTunnel: (port) => startCloudflareTunnel(port),
-                    onTunnelReady: (url) => console.error(`[fastagent] temporary tunnel ready → ${url}; registering webhook mode now…`),
-                    onPatchRetry: ({ error, attempt, attempts, retryMs }) => console.error(`[fastagent] Lark could not validate the fresh tunnel yet (${String(error)}); retrying PATCH ${attempt + 1}/${attempts} in ${Math.round(retryMs / 1000)}s…`),
-                    // A route-level 404 is definitive, not edge weather: fall back immediately.
-                    shouldRetryPatch: (error) => !isFeishuConfigApiMissing(error) && isTransientFeishuRegistrationError(error),
-                });
-                console.error(`[fastagent] Lark Verification Token captured; Subscription mode changed to webhook in the app draft`);
-                return { token };
-            }
-            catch (error) {
-                if (!isFeishuConfigApiMissing(error))
-                    throw error;
-                const manualReason = "This Lark app returned HTTP 404 for the application-config API, so automatic mode/token bootstrap is unavailable.";
-                console.error(`[fastagent] ${manualReason}`);
-                return { manualReason };
-            }
-        },
-    });
-    await checkAgentScopes({
-        kind: "lark",
-        appId: credentials.LARK_APP_ID,
-        apiBase,
-        ingress,
-        person,
-        api: createFeishuApi({
-            kind: "lark",
-            baseUrl: apiBase,
-            appId: credentials.LARK_APP_ID,
-            appSecret: credentials.LARK_APP_SECRET,
-        }),
-    });
-    return Object.fromEntries(Object.entries(credentials).filter((entry) => typeof entry[1] === "string"));
-}
-/** Lark's guided console at a terminal: what to open, and the values asked for there. */
-const larkAtTerminal = {
-    openUrl(url, action) {
-        clackLog.info(`${action}. Opening ${url}`);
-        openExternalUrl(url);
-    },
-    note: (message) => clackLog.info(message),
-    async prompt(message, opts) {
-        const result = opts?.hidden ? await password({ message }) : await clackText({ message });
-        return isCancel(result) ? undefined : result;
-    },
-};
-async function waitForLarkPage(person, page, action) {
-    const port = new URL(page.url).port;
-    try {
-        person.waitsOn(page.url, action +
-            " If the CLI runs remotely, forward this loopback port to the same local port " +
-            `(SSH: ssh -N -L ${port}:127.0.0.1:${port} user@host), then open the same URL in your browser. ` +
-            "Keep the forwarding session open; never paste secrets into the conversation.");
-        const value = await page.credentials;
-        person.carriesOn();
-        return value;
-    }
-    finally {
-        await page.close();
-    }
-}
-function larkThrough(person, target) {
-    return {
-        note: (message) => console.error(`[fastagent] ${message}`),
-        openUrl: (url, action) => person.afterwards(action, url),
-        async prompt() {
-            throw new Error("Lark setup must collect secrets on its page, not through terminal prompts");
-        },
-        async verificationToken(consoleUrl) {
-            const page = await startLarkVerificationPage({
-                consoleUrl,
-                save: async (token) => {
-                    await appendChannelDotEnv(target, "lark", { LARK_VERIFICATION_TOKEN: token }, ["LARK_VERIFICATION_TOKEN"]);
-                },
-            });
-            return waitForLarkPage(person, page, "Paste the Lark Verification Token on this page.");
-        },
-        async collect({ consoleUrl, check }) {
-            const page = await startLarkCredentialsPage({
-                consoleUrl,
-                check: async ({ appId, appSecret }) => {
-                    try {
-                        await check(appId, appSecret);
-                    }
-                    catch (error) {
-                        // Only a known credential refusal is safe to retry on the form.
-                        if (!isFeishuCredentialsRefused(error))
-                            throw error;
-                        throw new LarkCredentialsRefused("Lark refused that App ID or Secret.", {
-                            fix: "Copy both again from Credentials & Basic Info.",
-                            why: `Lark said: ${error instanceof Error ? error.message : String(error)}`,
-                        });
-                    }
-                },
-            });
-            return waitForLarkPage(person, page, "Create the Lark app, then paste its App ID and App Secret on this page.");
-        },
-    };
-}
-/** The scan-to-create flow `add feishu` runs by default. */
-async function createFeishuAppFlow(target, existing, ingress, rerun, person) {
-    const env = dotEnvPath(target); // the file actually written — never the default spelling
-    const { apiBase } = cloudFor("feishu");
-    let appId = existing.FEISHU_APP_ID;
-    let appSecret = existing.FEISHU_APP_SECRET;
-    if (appId && appSecret) {
-        console.error(ingress === "webhook"
-            ? `[fastagent] resuming Feishu app ${appId} from ${env} to capture its missing Verification Token`
-            : `[fastagent] reusing Feishu app ${appId} from ${env} for WebSocket ingress`);
-    }
-    else {
-        console.error(`[fastagent] creating the Feishu app (confirm in the app)…`);
-        const app = await registerFeishuApp({
-            name: process.env[AGENT_ENVIRONMENT_ENV] === "production" ? "{user}'s production agent" : "{user}'s agent",
-            desc: "Served by fastagent",
-            // The agent template alone is not enough to SERVE, nor to hear a group (see feishuAppAddons).
-            addons: feishuAppAddons(ingress),
-            onVerificationUrl: ({ url, expiresInS }) => person.waitsOn(url, "confirm the new Feishu app (in a browser, or in Feishu, or as a QR code)", Date.now() + expiresInS * 1000),
-        });
-        person.carriesOn();
-        console.error(`[fastagent] app created: ${app.appId}${app.tenantBrand ? ` (${app.tenantBrand} tenant)` : ""}`);
-        // A cross-brand confirmation should be impossible (each confirm page refuses the other brand's code).
-        if (app.tenantBrand && app.tenantBrand !== "feishu") {
-            throw new Error(`the confirming account is a ${app.tenantBrand} tenant, but this is \`add feishu\` — run \`fastagent add ${app.tenantBrand}\` instead`);
-        }
-        appId = app.appId;
-        appSecret = app.appSecret;
-        // IRREVERSIBLE BOUNDARY: the remote app now exists and its one-time Secret is in memory.
-        const staged = {
-            FEISHU_APP_ID: appId,
-            FEISHU_APP_SECRET: appSecret,
-            ...(ingress === "webhook" ? { FEISHU_VERIFICATION_TOKEN: "" } : {}),
-        };
-        await appendChannelDotEnv(target, "feishu", staged, Object.keys(staged), ingress);
-        console.error(ingress === "webhook"
-            ? `[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to ${env} before Token bootstrap`
-            : `[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to ${env}`);
-    }
-    const groupSetup = await checkAgentScopes({
-        kind: "feishu",
-        appId,
-        apiBase,
-        ingress,
-        api: createFeishuApi({ kind: "feishu", baseUrl: apiBase, appId, appSecret }),
-        person,
-    });
-    if (ingress === "websocket") {
-        const versionUrl = `${apiBase}/app/${appId}/version`;
-        const choose = "WebSocket ingress needs no Verification Token, Encrypt Key, Request URL, or tunnel: choose long connection in " +
-            "Events & Callbacks";
-        if (groupSetup.publishReady)
-            person.afterwards(`${choose}, then CREATE + PUBLISH a version`, versionUrl);
-        else
-            person.afterwards(`${choose}, finish the permission work above, then CREATE + PUBLISH a version: ${versionUrl}`);
-        return;
-    }
-    // The webhook channel authenticates plaintext events by the platform-generated Verification Token.
-    const tokenVar = "FEISHU_VERIFICATION_TOKEN";
-    const api = createFeishuApi({ baseUrl: apiBase, appId, appSecret });
-    let token;
-    let webhookModeChanged = false;
-    try {
-        const cfg = await api.getAppConfig(appId);
-        token = cfg.verificationToken;
-    }
-    catch (error) {
-        // Best-effort read; the bootstrap below is the real path. Said, because that path can take minutes and the reason
-        // it was needed would otherwise be invisible.
-        console.error(`[fastagent] could not read the app's Verification Token directly: ${error.message}`);
-    }
-    // The bootstrap registers a Request URL through the config scope; without it every attempt is refused, so it is not
-    // tried, and the reason is the one the permission check above already named.
-    const configWithheld = groupSetup.missing.includes(FEISHU_APP_CONFIG_SCOPE);
-    if (!token && configWithheld) {
-        console.error(`[fastagent] not capturing the Verification Token: the app is not granted ${FEISHU_APP_CONFIG_SCOPE}. Choose webhook ` +
-            `in Events & Callbacks and set the Request URL there yourself (dev --tunnel and deploy --run cannot ` +
-            `either), or have the permission approved and re-run \`${rerun}\`.`);
-    }
-    else if (!token) {
-        console.error(`[fastagent] capturing the Verification Token — a throwaway webhook registration delivers it (spinning up a temporary tunnel; can take a few minutes on a slow edge)…`);
-        try {
-            token = await bootstrapFeishuVerificationToken({
-                api,
-                appId,
-                startTunnel: (port) => startCloudflareTunnel(port),
-                // Only edge weather is retried; a refusal (scope, auth, app under review) is reported as itself.
-                shouldRetryPatch: isTransientFeishuRegistrationError,
-            });
-            webhookModeChanged = true;
-            console.error(`[fastagent] Verification Token captured`);
-        }
-        catch (e) {
-            console.error(`[fastagent] warn: could not capture the Verification Token: ${String(e)} — finish this app with the manual copy below`);
-        }
-    }
-    if (token) {
-        // Persist the second credential stage immediately too.
-        const staged = await appendChannelDotEnv(target, "feishu", { [tokenVar]: token }, [tokenVar]);
-        console.error(`[fastagent] wrote ${staged.written.join(", ")} to ${env}`);
-    }
-    else {
-        person.afterwards(`copy the Verification Token: developer console → Events & Callbacks → Encryption Strategy → Verification ` +
-            `Token → ${tokenVar} in ${env}`);
-    }
-    if (webhookModeChanged) {
-        // The bootstrap's PATCH flipped event mode in the DRAFT.
-        const versionUrl = `${apiBase}/app/${appId}/version`;
-        const publish = "CREATE + PUBLISH a version (self-approved): the switch to webhook mode takes effect on publish";
-        if (groupSetup.publishReady)
-            person.afterwards(publish, versionUrl);
-        else
-            person.afterwards(`after the permission work above, ${publish}: ${versionUrl}`);
-    }
-}
-/**
- * Active agent `.env` (`.secrets/.env`) values for the requested names — decided by THE .env parser, so this check can
- * never disagree with what `loadDotEnv` reads.
- */
-async function activeDotEnvValues(dir, names) {
-    let content;
-    try {
-        content = await readFile(dotEnvPath(dir), "utf8");
-    }
-    catch (e) {
-        if (e.code === "ENOENT")
-            return {};
-        throw e;
-    }
-    const parsed = parseEnvContent(content);
-    return Object.fromEntries(names.flatMap((name) => {
-        const value = parsed.get(name)?.trim();
-        return value ? [[name, value]] : [];
-    }));
-}
-export function feishuAppSecretNames(kind, ingress) {
-    const prefix = cloudFor(kind).envPrefix;
-    return [
-        `${prefix}_APP_ID`,
-        `${prefix}_APP_SECRET`,
-        ...(ingress === "webhook" ? [`${prefix}_VERIFICATION_TOKEN`] : []),
-    ];
-}
-export function unpreparedFeishuApps(channels, values) {
-    return ["feishu", "lark"].flatMap((kind) => {
-        const channel = channels.find((entry) => entry.name === kind);
-        if (!channel)
-            return [];
-        const ingress = channel.ingress === "webhook" ? "webhook" : "websocket";
-        return feishuAppSecretNames(kind, ingress).some((name) => !values.get(name)?.trim()) ? [{ kind, ingress }] : [];
-    });
-}
-export function assertIndependentFeishuApps(agentDir, kinds, values) {
-    const devFile = dotEnvPath(agentDir, {});
-    const devValues = loadEnvValues(devFile);
-    for (const kind of kinds) {
-        const name = `${cloudFor(kind).envPrefix}_APP_ID`;
-        const appId = values.get(name)?.trim();
-        if (appId && appId === devValues.get(name)?.trim()) {
-            throw new Error(`${kind}: dev and production use the same app (${name}) — create a separate production app in ` +
-                `${dotEnvPath(agentDir)}; copying dev credentials would take its messages away`);
-        }
-    }
-}
-export async function prepareFeishuApps(agentDir, apps, rerun, person, onboard = onboardFeishuCloudApp) {
-    for (const { kind, ingress } of apps) {
-        console.error(`[fastagent] ${kind}: preparing the production app for ${ingress} in ${dotEnvPath(agentDir)}`);
-        const created = await onboard(agentDir, kind, ingress, rerun, person);
-        if (created)
-            await appendChannelDotEnv(agentDir, kind, created, Object.keys(created), ingress);
-    }
-}