@fastagent-sh/fastagent 0.12.1 → 0.14.0

package/dist/cli/shared.js

@@ -0,0 +1,116 @@
+/**
+ * Helpers shared across command modules: interactivity gates, port parsing, the startup auth report,
+ * and first-run model resolution. Bodies moved verbatim from cli.ts; the module-scoped flag access
+ * (`values.*`) became parameters.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { autocomplete, isCancel, select } from "@clack/prompts";
+import { fastagentCredentialStore } from "../engines/pi/auth.js";
+import { isValidPort, loadConfig, resolveAuthPath, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
+import { configuredModelSpecs, createPiModels, probeAuthSource } from "../engines/pi/models.js";
+import { formatAuthReport } from "../cli-auth.js";
+import { log } from "../log.js";
+import { failStartup, failUsage } from "./fail.js";
+/** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+ * Parse + range-check a port string (CLI flag or env). Empty/whitespace is "not set" → undefined, so
+ * the `??` chain falls through instead of binding port 0 (`Number("")` is 0). The exit code follows
+ * RESPONSIBILITY, not the layer that discovers the problem: a bad `--port` is a usage error (2), a
+ * bad `PORT` env is broken runtime configuration (1).
+ */
+export function parsePort(value, source, from) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    if (!/^\d+$/.test(trimmed) || !isValidPort(Number(trimmed))) {
+        const message = `invalid ${source} "${value}": must be an integer 0-65535`;
+        if (from === "flag")
+            failUsage(message);
+        failStartup(new Error(message));
+    }
+    return Number(trimmed);
+}
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
+export async function reportAuth(modelSpec, authPath) {
+    const provider = modelSpec.slice(0, modelSpec.indexOf("/"));
+    const source = await probeAuthSource(createPiModels({ authPath }), modelSpec);
+    // Only when nothing satisfies auth do we read the store (refresh-FREE) to tell "nothing stored" from
+    // "stored but unusable" — see formatAuthReport for why. store.read warns on a corrupt file itself.
+    const stored = source === undefined
+        ? await fastagentCredentialStore(authPath)
+            .read(provider)
+            .catch(() => undefined)
+        : undefined;
+    const report = formatAuthReport(provider, authPath, source, stored);
+    log.info(`[fastagent] ${report.line}`);
+    if (report.warn)
+        log.warn(`[fastagent] ${report.warn}`);
+}
+/**
+ * First-run model resolution for the serving commands. When no model is set (flag/env/config), and
+ * we're on a TTY, pick one from the providers the user is logged into and persist the choice. A no-op
+ * when a model is already set; on a non-TTY (CI/deploy), or with `--no-input`, or with nothing
+ * configured it stays silent and lets the opener raise its clear "missing model" error. The pick is
+ * exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it, and best-effort written back to
+ * the config so the next run is quiet.
+ */
+export async function resolveFirstRunModel(workspaceDir, options = {}) {
+    const { config, path: configPath } = await loadConfig(workspaceDir).catch(failStartup);
+    if (resolveModelSpec(options.model, config))
+        return; // already set (flag > FASTAGENT_MODEL > config)
+    if (options.input === false)
+        return; // --no-input: never prompt (clig) — the opener raises the clear error
+    if (!isInteractive())
+        return; // CI/deploy: the opener throws the actionable missing-model error
+    const authPath = resolveAuthPath(workspaceDir, options.authPath);
+    let specs;
+    try {
+        specs = await configuredModelSpecs(createPiModels({ authPath }));
+    }
+    catch (error) {
+        // Enumerating providers/auth threw — a system fault (a corrupt auth store, a throwing provider),
+        // NOT "not logged in". Surface it instead of masking it as the login hint; the opener then still
+        // raises the clear missing-model error.
+        log.warn(`[fastagent] could not list configured models: ${error.message}`);
+        return;
+    }
+    if (specs.length === 0) {
+        log.warn(`[fastagent] no model set and no authenticated provider — run \`fastagent login\`, then \`fastagent dev\``);
+        return;
+    }
+    const r = await (specs.length > 7 ? autocomplete : select)({
+        message: "Choose a model for this agent",
+        options: specs.map((s) => ({ value: s, label: s })),
+    });
+    if (isCancel(r))
+        return; // cancelled: let the opener report the missing model
+    const chosen = r;
+    process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
+    await persistModelChoice(workspaceDir, configPath, chosen);
+}
+/**
+ * Best-effort persist the picked model so the next run does not prompt. Only rewrites the commented
+ * `model:` placeholder the scaffold writes (or an existing `model:` line); anything else (zero-config,
+ * a hand-shaped config) is left untouched with a printed hint. Never throws — persistence is a convenience.
+ */
+async function persistModelChoice(workspaceDir, configPath, spec) {
+    const hint = () => console.error(`[fastagent] using ${spec} for this run; set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
+    if (!configPath)
+        return hint();
+    try {
+        const replaced = rewriteConfigModel(await readFile(configPath, "utf8"), spec);
+        if (!replaced)
+            return hint();
+        await writeFile(configPath, replaced);
+        console.error(`[fastagent] saved model ${JSON.stringify(spec)} to ${relative(workspaceDir, configPath)}`);
+    }
+    catch {
+        hint();
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Create or resume the platform app behind `add feishu` / `add lark`. Returns credentials for the
+ * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
+ * the feishu path persists its own two credential stages internally (the App ID/Secret boundary is
+ * irreversible and must not wait for the caller). Throws on refusal (a committable .env, a
+ * non-interactive lark run); the caller surfaces that as a startup failure.
+ */
+export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", envIgnored: boolean): Promise<Record<string, string> | undefined>;

package/dist/cli-add-feishu.js

@@ -0,0 +1,223 @@
+/**
+ * `fastagent add feishu|lark` app onboarding — the cloud-facing half of runAdd, kept out of cli.ts
+ * (which self-executes on import), mirroring cli-models.ts/cli-auth.ts. The POLICY already lives in
+ * testable modules (register-app.ts, bootstrap-token.ts, lark/onboard.ts); this layer is the terminal
+ * wiring: clack prompts, .env staging, browser opens, progress lines.
+ *
+ * Feishu (scan-to-create): the device flow creates the app; App ID/Secret are persisted at the
+ * irreversible creation boundary, then the Verification Token is captured over a throwaway tunnel and
+ * persisted as a second stage — a re-run RESUMES the app instead of minting another. Lark
+ * (guided-console): open the unbound launcher, validate entered credentials, probe the same
+ * webhook/token bootstrap, and fall back to a manual token prompt on the definitive config-route 404.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isCancel, log as clackLog, password, text as clackText } from "@clack/prompts";
+import { bootstrapFeishuVerificationToken } from "./channels/feishu/bootstrap-token.js";
+import { cloudFor } from "./channels/feishu/cloud.js";
+import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError, } from "./channels/feishu/feishu-api.js";
+import { registerFeishuApp } from "./channels/feishu/register-app.js";
+import { onboardLarkApp } from "./channels/lark/onboard.js";
+import { parseEnvContent } from "./env.js";
+import { openExternalUrl } from "./open-url.js";
+import { appendChannelDotEnv } from "./scaffold/add-channel.js";
+import { startCloudflareTunnel } from "./tunnel.js";
+/**
+ * Create or resume the platform app behind `add feishu` / `add lark`. Returns credentials for the
+ * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
+ * the feishu path persists its own two credential stages internally (the App ID/Secret boundary is
+ * irreversible and must not wait for the caller). Throws on refusal (a committable .env, a
+ * non-interactive lark run); the caller surfaces that as a startup failure.
+ */
+export async function onboardFeishuCloudApp(target, kind, envIgnored) {
+    const { envPrefix, apiBase, capabilities } = cloudFor(kind);
+    // The CLI must never materialize a real credential into a committable file — refuse, don't warn.
+    if (!envIgnored) {
+        throw new Error(kind === "feishu"
+            ? "`add feishu` creates an app and writes real credentials to .env — add .env to .gitignore/.fastagentignore first, then re-run"
+            : "`add lark` writes real app credentials to .env — add .env to .gitignore/.fastagentignore first, then re-run");
+    }
+    const existing = await activeDotEnvValues(target, [
+        `${envPrefix}_APP_ID`,
+        `${envPrefix}_APP_SECRET`,
+        `${envPrefix}_VERIFICATION_TOKEN`,
+    ]);
+    if (Object.keys(existing).length === 3) {
+        console.error(`[fastagent] ${envPrefix}_APP_ID/SECRET/VERIFICATION_TOKEN already set in .env — keeping them`);
+        return undefined;
+    }
+    if (capabilities.appCreation === "scan-to-create") {
+        await createFeishuAppFlow(target, existing);
+        return undefined;
+    }
+    // guided-console (lark): the intl cloud cannot complete the bound device flow — collect + validate.
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        throw new Error("`add lark` needs an interactive terminal to onboard the Lark app credentials — re-run it in a terminal");
+    }
+    return onboardLarkApp({
+        openUrl: openExternalUrl,
+        note: (message) => clackLog.info(message),
+        async prompt(message, opts) {
+            const result = opts?.hidden ? await password({ message }) : await clackText({ message });
+            return isCancel(result) ? undefined : result;
+        },
+    }, {
+        existing,
+        verifyCredentials: async (appId, appSecret) => {
+            await createFeishuApi({ kind: "lark", baseUrl: apiBase, appId, appSecret }).verifyCredentials();
+            console.error(`[fastagent] Lark App ID / Secret verified`);
+        },
+        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. Retry only
+                    // actual edge/network weather; scope/auth/config failures remain immediate.
+                    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 };
+            }
+        },
+    });
+}
+/**
+ * The scan-to-create flow `add feishu` runs by default. The device-authorization grant
+ * creates a pre-configured agent app (bot capability, messaging scopes, event subscriptions) when the
+ * user confirms a link in the app, and hands back the credentials; App ID/Secret are persisted at that
+ * irreversible boundary before the platform-generated Verification Token is captured from the
+ * registration challenge (bootstrap-token.ts). The Token is persisted as a second stage, so .env is
+ * complete before the one remaining version-publish action. The event Request URL is NOT left pointing at the throwaway
+ * tunnel for long: `dev --tunnel` / `deploy --run` re-register it against the live URL.
+ *
+ * Feishu is the reference cloud and the only kind that runs this BOUND device flow. Lark is an explicit
+ * compatibility profile: its lagging control plane uses the unbound launcher + guided credentials,
+ * then probes the canonical token/mode bootstrap with a manual fallback.
+ */
+async function createFeishuAppFlow(target, existing) {
+    const { apiBase } = cloudFor("feishu");
+    let appId = existing.FEISHU_APP_ID;
+    let appSecret = existing.FEISHU_APP_SECRET;
+    if (appId && appSecret) {
+        console.error(`[fastagent] resuming Feishu app ${appId} from .env to capture its missing Verification Token`);
+    }
+    else {
+        console.error(`[fastagent] creating the Feishu app (confirm in the app)…`);
+        const app = await registerFeishuApp({
+            name: "{user}'s agent", // the platform expands {user} to the confirming user's name; editable on the page
+            desc: "Served by fastagent",
+            // The agent template alone is not enough to SERVE: the v7 config PATCH (webhook auto-registration
+            // in `dev --tunnel` / `deploy --run`) demands application:application:patch, and the app must
+            // subscribe the receive event. Addons merge both onto the confirm page — no manual app setup.
+            addons: {
+                scopes: { tenant: ["application:application:patch"] },
+                events: { items: { tenant: ["im.message.receive_v1"] } },
+            },
+            onVerificationUrl: ({ url, expiresInS }) => {
+                console.error(`\n  Opening the confirmation link in your browser (or open it in Feishu / render it as a QR code) — valid for ${Math.round(expiresInS / 60)} minutes:\n\n    ${url}\n\n  waiting for confirmation… (keep this running — the credentials are delivered here)`);
+                openExternalUrl(url); // best-effort, like `login` — the URL above is the fallback
+            },
+        });
+        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) — but if the platform ever reports one, the credentials would land in the WRONG kind's env
+        // namespace and serve the wrong cloud. Fail visibly instead of writing them.
+        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. Persist
+        // both before any config read, temporary tunnel, or Token bootstrap can be interrupted. Partial old
+        // lines are overwritten because these newly-minted credentials are authoritative as one pair.
+        await appendChannelDotEnv(target, "feishu", {
+            FEISHU_APP_ID: appId,
+            FEISHU_APP_SECRET: appSecret,
+            // A Token from a partial OLD credential set belongs to another App. Clear it at the same
+            // boundary; successful bootstrap below replaces the empty line with this App's Token.
+            FEISHU_VERIFICATION_TOKEN: "",
+        }, ["FEISHU_APP_ID", "FEISHU_APP_SECRET", "FEISHU_VERIFICATION_TOKEN"]);
+        console.error(`[fastagent] wrote FEISHU_APP_ID, FEISHU_APP_SECRET to .env before Token bootstrap`);
+    }
+    // The webhook channel authenticates plaintext events by the platform-generated Verification Token.
+    // Try the cheap read first (the v6 detail MAY someday return `encryption`), then the real path: the
+    // token's only programmatic delivery is the url_verification challenge during registration — capture
+    // it over a throwaway tunnel (bootstrap-token.ts). Failing both is a one-line manual copy; the staged
+    // ID/Secret pair makes a re-run resume this App rather than mint another one.
+    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 {
+        /* the read surface is best-effort — the bootstrap below is the real path */
+    }
+    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),
+            });
+            webhookModeChanged = true;
+            console.error(`[fastagent] Verification Token captured`);
+        }
+        catch (e) {
+            // Transient tunnel weather is the usual cause. Do NOT suggest re-running `add feishu` as a new
+            // scan: the staged pair makes the re-run resume THIS app; manual copy completes it too.
+            console.error(`[fastagent] warn: could not capture the Verification Token: ${String(e)} — usually a transient tunnel issue; finish this app with the manual copy below`);
+        }
+    }
+    if (token) {
+        // Persist the second credential stage immediately too — opening the publish page and generic
+        // scaffold finalization happen only after the complete runtime credential set is durable.
+        const staged = await appendChannelDotEnv(target, "feishu", { [tokenVar]: token }, [tokenVar]);
+        console.error(`[fastagent] wrote ${staged.written.join(", ")} to .env`);
+    }
+    else {
+        console.error(`[fastagent] copy it manually: developer console → Events & Callbacks → Encryption Strategy → Verification Token → ${tokenVar} in .env`);
+    }
+    if (webhookModeChanged) {
+        // The bootstrap's PATCH flipped event mode in the DRAFT. It takes effect only after a version
+        // publish, which has no API; later dev/deploy runs change only the Request URL immediately.
+        const versionUrl = `${apiBase}/app/${appId}/version`;
+        console.error(`[fastagent] one console click remains: CREATE + PUBLISH a version (self-approved) — the switch to webhook mode takes effect on publish. Opening ${versionUrl}`);
+        openExternalUrl(versionUrl);
+    }
+}
+/** Active run-root `.env` values for the requested names — decided by THE .env parser, so this
+ * check can never disagree with what `loadEnvFile` reads. Empty/commented values are absent. */
+async function activeDotEnvValues(dir, names) {
+    let content;
+    try {
+        content = await readFile(join(dir, ".env"), "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]] : [];
+    }));
+}