@agent-native/core 0.113.0 → 0.114.0

package/src/onboarding/default-steps.ts

@@ -0,0 +1,428 @@
+/**
+ * Default framework-level onboarding steps.
+ *
+ * Registered when `createOnboardingPlugin()` mounts (auto-mount or explicit).
+ * Templates can override any step by registering another step with the same
+ * `id` after these have been registered.
+ */
+
+import {
+  PROVIDER_ENV_META,
+  PROVIDER_ENV_VARS,
+} from "../agent/engine/provider-env-vars.js";
+import {
+  detectEngineFromUserSecrets,
+  isAgentEngineSettingConfigured,
+} from "../agent/engine/registry.js";
+import {
+  canUseDeployCredentialFallbackForRequest,
+  readDeployCredentialEnv,
+  resolveSecret,
+} from "../server/credential-provider.js";
+import { getSetting } from "../settings/store.js";
+import { registerOnboardingStep } from "./registry.js";
+import type { OnboardingStep } from "./types.js";
+
+type LlmKeyMethod = {
+  provider: keyof typeof PROVIDER_ENV_META;
+  id: string;
+  label: string;
+  description: string;
+  primary?: boolean;
+};
+
+const LLM_KEY_METHODS: LlmKeyMethod[] = [
+  {
+    provider: "anthropic",
+    id: "anthropic-key",
+    label: "Anthropic",
+    description: "Claude models with your own Anthropic key.",
+  },
+  {
+    provider: "openai",
+    id: "openai-key",
+    label: "OpenAI",
+    description: "GPT models with your own OpenAI key.",
+  },
+  {
+    provider: "google",
+    id: "google-key",
+    label: "Google Gemini",
+    description: "Gemini models with your own Google AI key.",
+  },
+  {
+    provider: "openrouter",
+    id: "openrouter-key",
+    label: "OpenRouter",
+    description: "OpenRouter models, including GLM 5.2, with your own key.",
+  },
+  {
+    provider: "groq",
+    id: "groq-key",
+    label: "Groq",
+    description: "Groq-hosted models with your own Groq key.",
+  },
+  {
+    provider: "mistral",
+    id: "mistral-key",
+    label: "Mistral",
+    description: "Mistral models with your own Mistral key.",
+  },
+  {
+    provider: "cohere",
+    id: "cohere-key",
+    label: "Cohere",
+    description: "Cohere models with your own Cohere key.",
+  },
+];
+
+const llmStep: OnboardingStep = {
+  id: "llm",
+  order: 10,
+  required: true,
+  title: "Connect an AI engine",
+  description: "Use Builder's managed gateway, or bring your own provider key.",
+  methods: [
+    {
+      id: "builder",
+      kind: "builder-cli-auth",
+      label: "Connect Builder",
+      description: "Builder.io's free tier includes AI credits.",
+      primary: true,
+      badge: "free",
+      payload: {
+        scope: "llm",
+      },
+    },
+    ...LLM_KEY_METHODS.map(({ provider, id, label, description, primary }) => {
+      const meta = PROVIDER_ENV_META[provider];
+      return {
+        id,
+        kind: "form" as const,
+        label,
+        description,
+        ...(primary ? { primary: true } : {}),
+        payload: {
+          writeScope: "workspace" as const,
+          fields: [
+            {
+              key: meta.envVar,
+              label: meta.envVar,
+              placeholder: meta.placeholder,
+              secret: true,
+            },
+          ],
+        },
+      };
+    }),
+  ],
+  isComplete: async () => {
+    try {
+      const { resolveHasCompleteBuilderConnection } =
+        await import("../server/credential-provider.js");
+      if (await resolveHasCompleteBuilderConnection()) return true;
+    } catch {
+      // Credential storage may be unavailable during early boot. Do not fall
+      // back to deployment-level Builder env here; the scoped resolver owns the
+      // policy for when that is safe.
+    }
+    try {
+      if (await detectEngineFromUserSecrets()) return true;
+    } catch {
+      // Fall through to legacy/env detection.
+    }
+    if (
+      PROVIDER_ENV_VARS.some(
+        (k) =>
+          canUseDeployCredentialFallbackForRequest(k) &&
+          !!readDeployCredentialEnv(k),
+      )
+    ) {
+      return true;
+    }
+    try {
+      return isAgentEngineSettingConfigured(await getSetting("agent-engine"));
+    } catch {
+      return false;
+    }
+  },
+};
+
+/** Step 2 — where application data lives. The default DB is non-blocking. */
+const databaseStep: OnboardingStep = {
+  id: "database",
+  order: 20,
+  required: false,
+  title: "Database",
+  description:
+    "Agent-native stores app data in SQL. Set DATABASE_URL when you want to point this app at a specific database or opt into local PGlite.",
+  methods: [
+    {
+      id: "database-url",
+      kind: "form",
+      label: "Set DATABASE_URL",
+      description: "Paste the SQL connection string this app should use.",
+      payload: {
+        writeScope: "workspace",
+        fields: [
+          {
+            key: "DATABASE_URL",
+            label: "DATABASE_URL",
+            placeholder:
+              "postgres://..., libsql://..., file:./data/app.db, pglite:./data/pglite",
+          },
+          {
+            key: "DATABASE_AUTH_TOKEN",
+            label: "DATABASE_AUTH_TOKEN (if needed)",
+            placeholder: "Token for providers such as Turso/libSQL",
+            secret: true,
+          },
+        ],
+      },
+    },
+  ],
+  // The default local database means this step is always satisfied.
+  isComplete: () => true,
+};
+
+/** Step 3 — how users sign in. Built-in account auth is non-blocking. */
+const authStep: OnboardingStep = {
+  id: "auth",
+  order: 30,
+  required: false,
+  title: "Authentication",
+  description:
+    "Built-in email/password accounts work by default. Add OAuth or access tokens only if you want another sign-in path.",
+  methods: [
+    {
+      id: "google-oauth",
+      kind: "form",
+      label: "Google OAuth",
+      description: "Add Google as an optional sign-in provider.",
+      payload: {
+        writeScope: "workspace",
+        fields: [
+          { key: "GOOGLE_CLIENT_ID", label: "GOOGLE_CLIENT_ID" },
+          {
+            key: "GOOGLE_CLIENT_SECRET",
+            label: "GOOGLE_CLIENT_SECRET",
+            secret: true,
+          },
+        ],
+      },
+    },
+    {
+      id: "github-oauth",
+      kind: "form",
+      label: "GitHub OAuth",
+      description: "Add GitHub as an optional sign-in provider.",
+      payload: {
+        writeScope: "workspace",
+        fields: [
+          { key: "GITHUB_CLIENT_ID", label: "GITHUB_CLIENT_ID" },
+          {
+            key: "GITHUB_CLIENT_SECRET",
+            label: "GITHUB_CLIENT_SECRET",
+            secret: true,
+          },
+        ],
+      },
+    },
+  ],
+  isComplete: () => true,
+};
+
+/** Step 4 — transactional email (password resets, invitations). Optional. */
+const emailStep: OnboardingStep = {
+  id: "email",
+  order: 40,
+  required: false,
+  title: "Email delivery",
+  description:
+    "Optional for local work. Before deploying with password resets, invitations, or share notifications, connect an email provider.",
+  methods: [
+    {
+      id: "resend",
+      kind: "form",
+      label: "Resend",
+      description: "Use Resend for transactional email.",
+      payload: {
+        writeScope: "workspace",
+        fields: [
+          {
+            key: "RESEND_API_KEY",
+            label: "RESEND_API_KEY",
+            placeholder: "re_...",
+            secret: true,
+          },
+          {
+            key: "EMAIL_FROM",
+            label: "EMAIL_FROM (from address)",
+            placeholder: "Agent Native <noreply@yourdomain.com>",
+          },
+          {
+            key: "APP_NAME",
+            label: "APP_NAME (shown in invite emails)",
+            placeholder: "Acme Forms",
+          },
+        ],
+      },
+    },
+    {
+      id: "sendgrid",
+      kind: "form",
+      label: "SendGrid",
+      description: "Use SendGrid for transactional email.",
+      payload: {
+        writeScope: "workspace",
+        fields: [
+          {
+            key: "SENDGRID_API_KEY",
+            label: "SENDGRID_API_KEY",
+            placeholder: "SG....",
+            secret: true,
+          },
+          {
+            key: "EMAIL_FROM",
+            label: "EMAIL_FROM (from address)",
+            placeholder: "Agent Native <noreply@yourdomain.com>",
+          },
+        ],
+      },
+    },
+  ],
+  isComplete: async () => {
+    if (await resolveSecret("RESEND_API_KEY")) return true;
+    // SendGrid rejects Resend's sandbox sender, so EMAIL_FROM must also be
+    // set — otherwise sendEmail() throws at runtime even though the API key
+    // is configured.
+    if (await resolveSecret("SENDGRID_API_KEY")) {
+      return !!(await resolveSecret("EMAIL_FROM"));
+    }
+    return false;
+  },
+};
+
+const githubRepositoryStep: OnboardingStep = {
+  id: "github-repository",
+  order: 50,
+  required: false,
+  title: "Connect a GitHub repository",
+  description:
+    "Optional for cloud/headless repo work. Grants connector-scoped file read and write access without cloning a repo or running code.",
+  methods: [
+    {
+      id: "settings",
+      kind: "link",
+      primary: true,
+      label: "Open GitHub token settings",
+      description:
+        "Save a fine-grained token scoped to the repositories this workspace may access.",
+      payload: {
+        url: "#secrets:GITHUB_TOKEN",
+        external: false,
+      },
+    },
+    {
+      id: "local-env",
+      kind: "form",
+      label: "Use local .env",
+      description:
+        "For local/single-tenant work, save a token and optional default owner/repo.",
+      payload: {
+        writeScope: "workspace",
+        fields: [
+          {
+            key: "GITHUB_TOKEN",
+            label: "GITHUB_TOKEN",
+            placeholder: "github_pat_...",
+            secret: true,
+          },
+          {
+            key: "GITHUB_REPOSITORY",
+            label: "GITHUB_REPOSITORY",
+            placeholder: "owner/repo",
+          },
+        ],
+      },
+    },
+  ],
+  isComplete: async (context) => {
+    const userEmail = context?.userEmail;
+    const orgId = context?.orgId ?? null;
+    if (userEmail) {
+      try {
+        const { resolveWorkspaceConnectionCredentialForApp } =
+          await import("../workspace-connections/index.js");
+        const result = await resolveWorkspaceConnectionCredentialForApp({
+          appId:
+            process.env.AGENT_NATIVE_APP_ID ||
+            process.env.APP_ID ||
+            process.env.npm_package_name ||
+            "app",
+          provider: "github",
+          key: "GITHUB_TOKEN",
+          userEmail,
+          orgId,
+        });
+        if (result.available) return true;
+      } catch {
+        // Fall through to local credential stores.
+      }
+
+      try {
+        const { resolveCredential } = await import("../credentials/index.js");
+        if (await resolveCredential("GITHUB_TOKEN", { userEmail, orgId })) {
+          return true;
+        }
+      } catch {
+        // Fall through to app_secrets.
+      }
+
+      try {
+        const { readAppSecretMeta } = await import("../secrets/storage.js");
+        const refs: Array<{
+          scope: "user" | "org" | "workspace";
+          scopeId: string;
+        }> = [{ scope: "user", scopeId: userEmail }];
+        if (orgId) {
+          refs.push(
+            { scope: "org", scopeId: orgId },
+            { scope: "workspace", scopeId: orgId },
+          );
+        } else {
+          refs.push({ scope: "workspace", scopeId: `solo:${userEmail}` });
+        }
+        for (const ref of refs) {
+          const meta = await readAppSecretMeta({
+            key: "GITHUB_TOKEN",
+            scope: ref.scope,
+            scopeId: ref.scopeId,
+          });
+          if (meta) return true;
+        }
+      } catch {
+        // Fall through to local/single-tenant env.
+      }
+    }
+
+    if (!canUseDeployCredentialFallbackForRequest()) return false;
+    return !!(
+      readDeployCredentialEnv("GITHUB_TOKEN") ||
+      readDeployCredentialEnv("GH_TOKEN")
+    );
+  },
+};
+
+let registered = false;
+
+/** Idempotent. Safe to call from every plugin-mount call. */
+export function registerDefaultOnboardingSteps(): void {
+  if (registered) return;
+  registered = true;
+  registerOnboardingStep(llmStep);
+  registerOnboardingStep(databaseStep);
+  registerOnboardingStep(authStep);
+  registerOnboardingStep(emailStep);
+  registerOnboardingStep(githubRepositoryStep);
+}

package/src/onboarding/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Framework-level onboarding system.
+ *
+ * Templates register steps the agent sidebar should show as a setup checklist.
+ * The server auto-mounts `/_agent-native/onboarding/*` routes and the client
+ * hook polls them — see `@agent-native/core/client/onboarding`.
+ */
+
+export { registerOnboardingStep, listOnboardingSteps } from "./registry.js";
+export type {
+  OnboardingStep,
+  OnboardingMethod,
+  OnboardingMethodBadge,
+  OnboardingFormField,
+  OnboardingStepStatus,
+} from "./types.js";
+export {
+  createOnboardingPlugin,
+  defaultOnboardingPlugin,
+  type OnboardingPluginOptions,
+} from "./plugin.js";
+export { registerDefaultOnboardingSteps } from "./default-steps.js";

package/src/onboarding/plugin.ts

@@ -0,0 +1,262 @@
+/**
+ * Onboarding plugin — auto-mounts the `/_agent-native/onboarding/*` routes.
+ *
+ * Routes:
+ *   GET  /_agent-native/onboarding/steps              — list steps + completion
+ *   POST /_agent-native/onboarding/steps/:id/complete — manual override (marks complete)
+ *   POST /_agent-native/onboarding/dismiss            — dismiss the banner
+ *   GET  /_agent-native/onboarding/dismissed          — dismissed flag + allComplete
+ */
+
+import {
+  defineEventHandler,
+  getMethod,
+  getQuery,
+  setResponseStatus,
+  type H3Event,
+} from "h3";
+
+import { appStateGet, appStatePut } from "../application-state/store.js";
+import { getSession } from "../server/auth.js";
+import {
+  awaitBootstrap,
+  getH3App,
+  markDefaultPluginProvided,
+} from "../server/framework-request-handler.js";
+import { runWithRequestContext } from "../server/request-context.js";
+import { registerDefaultOnboardingSteps } from "./default-steps.js";
+import { listOnboardingSteps } from "./registry.js";
+import type {
+  OnboardingResolveContext,
+  OnboardingStepStatus,
+} from "./types.js";
+
+type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
+
+const ONBOARDING_PREFIX = "/_agent-native/onboarding";
+const OVERRIDE_KEY_PREFIX = "onboarding:override:";
+const DISMISSED_KEY = "onboarding:dismissed";
+
+export interface OnboardingPluginOptions {
+  /** Skip registering the built-in default steps (llm, database, auth). */
+  skipDefaultSteps?: boolean;
+}
+
+/** Resolve the caller context used for onboarding and application-state scoping. */
+async function resolveOnboardingContext(
+  event: H3Event,
+): Promise<OnboardingResolveContext> {
+  const session = await getSession(event);
+  if (!session) return { sessionId: "local" };
+  return {
+    sessionId: session.email,
+    userEmail: session.email,
+    orgId: session.orgId ?? null,
+  };
+}
+
+async function hasOverride(
+  sessionId: string,
+  stepId: string,
+): Promise<boolean> {
+  // appStateGet hits the DB; on transient connection errors (flaky network /
+  // Neon timeout) treat as "no override" rather than 500ing the whole route.
+  try {
+    const val = await appStateGet(sessionId, `${OVERRIDE_KEY_PREFIX}${stepId}`);
+    return !!(val && (val as { complete?: boolean }).complete);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Serialise every registered onboarding step (awaiting `isComplete()`).
+ * Honours the per-session "manual override" flag in application-state.
+ *
+ * `preview` short-circuits both the resolver and the override lookup so the
+ * dev overlay can render the new-user flow without touching real state.
+ */
+async function serializeSteps(
+  context: OnboardingResolveContext,
+  options: { preview?: boolean } = {},
+): Promise<OnboardingStepStatus[]> {
+  const steps = listOnboardingSteps();
+  const out: OnboardingStepStatus[] = [];
+  for (const step of steps) {
+    let complete = false;
+    if (!options.preview) {
+      try {
+        complete = (await step.isComplete(context)) === true;
+      } catch {
+        complete = false;
+      }
+      if (!complete) {
+        complete = await hasOverride(context.sessionId, step.id);
+      }
+    }
+    out.push({
+      id: step.id,
+      title: step.title,
+      description: step.description,
+      order: step.order,
+      required: step.required ?? false,
+      complete,
+      methods: step.methods,
+    });
+  }
+  return out;
+}
+
+function withOnboardingRequestContext<T>(
+  context: OnboardingResolveContext,
+  fn: () => T | Promise<T>,
+): T | Promise<T> {
+  return runWithRequestContext(
+    {
+      userEmail: context.userEmail,
+      orgId: context.orgId ?? undefined,
+    },
+    fn,
+  );
+}
+
+function allRequiredComplete(statuses: OnboardingStepStatus[]): boolean {
+  return statuses.filter((s) => s.required).every((s) => s.complete);
+}
+
+export function createOnboardingPlugin(
+  options: OnboardingPluginOptions = {},
+): NitroPluginDef {
+  return async (nitroApp: any) => {
+    markDefaultPluginProvided(nitroApp, "onboarding");
+    await awaitBootstrap(nitroApp);
+
+    if (!options.skipDefaultSteps) {
+      registerDefaultOnboardingSteps();
+    }
+
+    // GET  /_agent-native/onboarding/steps              — list steps
+    // POST /_agent-native/onboarding/steps/:id/complete — manual override
+    //
+    // Mounting on `/steps` means the middleware wrapper strips that prefix,
+    // so this handler sees `/` for the list and `/<stepId>/complete` for the
+    // override.
+    getH3App(nitroApp).use(
+      `${ONBOARDING_PREFIX}/steps`,
+      defineEventHandler(async (event: H3Event) => {
+        const method = getMethod(event);
+        const pathname = event.url?.pathname || "/";
+        const trimmed = pathname.replace(/^\/+/, "").replace(/\/+$/, "");
+
+        // List endpoint — GET /steps (pathname becomes "" or "/")
+        if (trimmed === "") {
+          if (method !== "GET") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+          }
+          const context = await resolveOnboardingContext(event);
+          const query = getQuery(event) as Record<string, unknown>;
+          const preview = query.preview === "1" || query.preview === 1;
+          return withOnboardingRequestContext(context, () =>
+            serializeSteps(context, { preview }),
+          );
+        }
+
+        // Override endpoint — POST /steps/:id/complete
+        const [id, action] = trimmed.split("/");
+        if (action === "complete") {
+          if (method !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+          }
+          if (!id) {
+            setResponseStatus(event, 400);
+            return { error: "id required" };
+          }
+          const { sessionId } = await resolveOnboardingContext(event);
+          await appStatePut(
+            sessionId,
+            `${OVERRIDE_KEY_PREFIX}${id}`,
+            { complete: true },
+            { requestSource: "agent" },
+          );
+          return { ok: true, id };
+        }
+
+        // Unknown subroute — fall through to other middleware.
+        return;
+      }),
+    );
+
+    // POST /_agent-native/onboarding/dismiss
+    getH3App(nitroApp).use(
+      `${ONBOARDING_PREFIX}/dismiss`,
+      defineEventHandler(async (event: H3Event) => {
+        if (getMethod(event) !== "POST") {
+          setResponseStatus(event, 405);
+          return { error: "Method not allowed" };
+        }
+        const { sessionId } = await resolveOnboardingContext(event);
+        await appStatePut(
+          sessionId,
+          DISMISSED_KEY,
+          { dismissed: true, at: new Date().toISOString() },
+          { requestSource: "agent" },
+        );
+        return { ok: true };
+      }),
+    );
+
+    // POST /_agent-native/onboarding/reopen — clear dismissed flag
+    getH3App(nitroApp).use(
+      `${ONBOARDING_PREFIX}/reopen`,
+      defineEventHandler(async (event: H3Event) => {
+        if (getMethod(event) !== "POST") {
+          setResponseStatus(event, 405);
+          return { error: "Method not allowed" };
+        }
+        const { sessionId } = await resolveOnboardingContext(event);
+        await appStatePut(
+          sessionId,
+          DISMISSED_KEY,
+          { dismissed: false, at: new Date().toISOString() },
+          { requestSource: "agent" },
+        );
+        return { ok: true };
+      }),
+    );
+
+    // GET /_agent-native/onboarding/dismissed
+    getH3App(nitroApp).use(
+      `${ONBOARDING_PREFIX}/dismissed`,
+      defineEventHandler(async (event: H3Event) => {
+        if (getMethod(event) !== "GET") {
+          setResponseStatus(event, 405);
+          return { error: "Method not allowed" };
+        }
+        const context = await resolveOnboardingContext(event);
+        // On flaky networks (or transient Neon hiccups) the DB call below
+        // can throw — return safe defaults so a transient connection error
+        // doesn't surface as a 500 to the client.
+        try {
+          return await withOnboardingRequestContext(context, async () => {
+            const value = await appStateGet(context.sessionId, DISMISSED_KEY);
+            const dismissed = !!(
+              value && (value as { dismissed?: boolean }).dismissed
+            );
+            const statuses = await serializeSteps(context);
+            return {
+              dismissed,
+              allComplete: allRequiredComplete(statuses),
+            };
+          });
+        } catch {
+          return { dismissed: false, allComplete: false };
+        }
+      }),
+    );
+  };
+}
+
+/** Default plugin instance — mounted automatically when a template doesn't override. */
+export const defaultOnboardingPlugin: NitroPluginDef = createOnboardingPlugin();