@agent-native/core 0.5.0-dev.b51eaae → 0.7.1

package/dist/oauth-tokens/store.js

@@ -21,6 +21,13 @@ async function ensureTable() {
             catch {
                 // Column already exists
             }
+            // Migration: add display_name column
+            try {
+                await client.execute(`ALTER TABLE oauth_tokens ADD COLUMN display_name TEXT`);
+            }
+            catch {
+                // Column already exists
+            }
             // Backfill: set owner = account_id for existing rows without an owner
             await client.execute(`UPDATE oauth_tokens SET owner = account_id WHERE owner IS NULL`);
         })();
@@ -49,26 +56,32 @@ export async function getOAuthTokens(provider, accountId) {
 export async function saveOAuthTokens(provider, accountId, tokens, owner) {
     await ensureTable();
     const client = getDbExec();
+    // Never store "local@localhost" as owner — it creates shared-ownership bugs
+    const sanitizedOwner = owner === "local@localhost" ? accountId : owner;
     // When owner is not provided (e.g. during token refresh), preserve the existing
-    // owner so secondary accounts don't get silently re-assigned to accountId.
-    let resolvedOwner = owner ?? accountId;
+    // owner and display_name so they don't get wiped by INSERT OR REPLACE.
+    let resolvedOwner = sanitizedOwner ?? accountId;
+    let existingDisplayName = null;
     if (!owner) {
         const { rows: existing } = await client.execute({
-            sql: `SELECT owner FROM oauth_tokens WHERE provider = ? AND account_id = ?`,
+            sql: `SELECT owner, display_name FROM oauth_tokens WHERE provider = ? AND account_id = ?`,
             args: [provider, accountId],
         });
-        if (existing.length > 0 && existing[0].owner) {
-            resolvedOwner = existing[0].owner;
+        if (existing.length > 0) {
+            if (existing[0].owner)
+                resolvedOwner = existing[0].owner;
+            existingDisplayName = existing[0].display_name ?? null;
         }
     }
     await client.execute({
         sql: isPostgres()
-            ? `INSERT INTO oauth_tokens (provider, account_id, owner, tokens, updated_at) VALUES (?, ?, ?, ?, ?) ON CONFLICT (provider, account_id) DO UPDATE SET owner=EXCLUDED.owner, tokens=EXCLUDED.tokens, updated_at=EXCLUDED.updated_at`
-            : `INSERT OR REPLACE INTO oauth_tokens (provider, account_id, owner, tokens, updated_at) VALUES (?, ?, ?, ?, ?)`,
+            ? `INSERT INTO oauth_tokens (provider, account_id, owner, display_name, tokens, updated_at) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (provider, account_id) DO UPDATE SET owner=EXCLUDED.owner, display_name=COALESCE(EXCLUDED.display_name, oauth_tokens.display_name), tokens=EXCLUDED.tokens, updated_at=EXCLUDED.updated_at`
+            : `INSERT OR REPLACE INTO oauth_tokens (provider, account_id, owner, display_name, tokens, updated_at) VALUES (?, ?, ?, ?, ?, ?)`,
         args: [
             provider,
             accountId,
             resolvedOwner,
+            existingDisplayName,
             JSON.stringify(tokens),
             Date.now(),
         ],
@@ -111,14 +124,26 @@ export async function listOAuthAccountsByOwner(provider, owner) {
     await ensureTable();
     const client = getDbExec();
     const { rows } = await client.execute({
-        sql: `SELECT account_id, tokens FROM oauth_tokens WHERE provider = ? AND owner = ?`,
+        sql: `SELECT account_id, display_name, tokens FROM oauth_tokens WHERE provider = ? AND owner = ?`,
         args: [provider, owner],
     });
     return rows.map((row) => ({
         accountId: row.account_id,
+        displayName: row.display_name ?? null,
         tokens: JSON.parse(row.tokens),
     }));
 }
+/**
+ * Set the display name for an OAuth account (e.g. Google profile name).
+ */
+export async function setOAuthDisplayName(provider, accountId, displayName) {
+    await ensureTable();
+    const client = getDbExec();
+    await client.execute({
+        sql: `UPDATE oauth_tokens SET display_name = ? WHERE provider = ? AND account_id = ?`,
+        args: [displayName, provider, accountId],
+    });
+}
 export async function hasOAuthTokens(provider) {
     await ensureTable();
     const client = getDbExec();

package/dist/oauth-tokens/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/oauth-tokens/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/oauth-tokens/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAe,MAAM,iBAAiB,CAAC;AAE9E,IAAI,YAAuC,CAAC;AAE5C,KAAK,UAAU,WAAW;IACxB,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,CAAC,KAAK,IAAI,EAAE;YACzB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;YAC3B,MAAM,MAAM,CAAC,OAAO,CAAC;;;;;;uBAMJ,OAAO,EAAE;;;OAGzB,CAAC,CAAC;YACH,iDAAiD;YACjD,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,OAAO,CAAC,gDAAgD,CAAC,CAAC;YACzE,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;YACD,qCAAqC;YACrC,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,OAAO,CAClB,uDAAuD,CACxD,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;YACD,sEAAsE;YACtE,MAAM,MAAM,CAAC,OAAO,CAClB,gEAAgE,CACjE,CAAC;QACJ,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAAgB,EAChB,SAAiB;IAEjB,MAAM,WAAW,EAAE,CAAC;IACpB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACpC,GAAG,EAAE,uEAAuE;QAC5E,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;KAC5B,CAAC,CAAC;IACH,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAgB,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,SAAiB,EACjB,MAA+B,EAC/B,KAAc;IAEd,MAAM,WAAW,EAAE,CAAC;IACpB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAE3B,4EAA4E;IAC5E,MAAM,cAAc,GAAG,KAAK,KAAK,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;IAEvE,gFAAgF;IAChF,uEAAuE;IACvE,IAAI,aAAa,GAAG,cAAc,IAAI,SAAS,CAAC;IAChD,IAAI,mBAAmB,GAAkB,IAAI,CAAC;IAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;YAC9C,GAAG,EAAE,oFAAoF;YACzF,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;SAC5B,CAAC,CAAC;QACH,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK;gBAAE,aAAa,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAe,CAAC;YACnE,mBAAmB,GAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAuB,IAAI,IAAI,CAAC;QACrE,CAAC;IACH,CAAC;IAED,MAAM,MAAM,CAAC,OAAO,CAAC;QACnB,GAAG,EAAE,UAAU,EAAE;YACf,CAAC,CAAC,2TAA2T;YAC7T,CAAC,CAAC,+HAA+H;QACnI,IAAI,EAAE;YACJ,QAAQ;YACR,SAAS;YACT,aAAa;YACb,mBAAmB;YACnB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;YACtB,IAAI,CAAC,GAAG,EAAE;SACX;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,SAAkB;IAElB,MAAM,WAAW,EAAE,CAAC;IACpB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;YAClC,GAAG,EAAE,gEAAgE;YACrE,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;SAC5B,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,YAAY,CAAC;IAC7B,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QAClC,GAAG,EAAE,6CAA6C;QAClD,IAAI,EAAE,CAAC,QAAQ,CAAC;KACjB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,YAAY,CAAC;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IAOtD,MAAM,WAAW,EAAE,CAAC;IACpB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACpC,GAAG,EAAE,uEAAuE;QAC5E,IAAI,EAAE,CAAC,QAAQ,CAAC;KACjB,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxB,SAAS,EAAE,GAAG,CAAC,UAAoB;QACnC,KAAK,EAAG,GAAG,CAAC,KAAgB,IAAI,IAAI;QACpC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAgB,CAAC;KACzC,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,QAAgB,EAChB,KAAa;IAQb,MAAM,WAAW,EAAE,CAAC;IACpB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACpC,GAAG,EAAE,4FAA4F;QACjG,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC;KACxB,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxB,SAAS,EAAE,GAAG,CAAC,UAAoB;QACnC,WAAW,EAAG,GAAG,CAAC,YAAuB,IAAI,IAAI;QACjD,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAgB,CAAC;KACzC,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,QAAgB,EAChB,SAAiB,EACjB,WAAmB;IAEnB,MAAM,WAAW,EAAE,CAAC;IACpB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,MAAM,CAAC,OAAO,CAAC;QACnB,GAAG,EAAE,gFAAgF;QACrF,IAAI,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC;KACzC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB;IACnD,MAAM,WAAW,EAAE,CAAC;IACpB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACpC,GAAG,EAAE,uDAAuD;QAC5D,IAAI,EAAE,CAAC,QAAQ,CAAC;KACjB,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/dist/onboarding/default-steps.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+/** Idempotent. Safe to call from every plugin-mount call. */
+export declare function registerDefaultOnboardingSteps(): void;
+//# sourceMappingURL=default-steps.d.ts.map

package/dist/onboarding/default-steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-steps.d.ts","sourceRoot":"","sources":["../../src/onboarding/default-steps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4JH,6DAA6D;AAC7D,wBAAgB,8BAA8B,IAAI,IAAI,CAOrD"}

package/dist/onboarding/default-steps.js

@@ -0,0 +1,164 @@
+/**
+ * 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 { registerOnboardingStep } from "./registry.js";
+/** Step 1 — an LLM must be reachable for the agent chat to work. */
+const llmStep = {
+    id: "llm",
+    order: 10,
+    required: true,
+    title: "Connect an AI engine",
+    description: "Agent-native needs an LLM to power the agent chat.",
+    methods: [
+        {
+            id: "anthropic-key",
+            kind: "form",
+            label: "Use your Anthropic API key",
+            description: "Paste a key — stored locally in your .env file.",
+            primary: true,
+            payload: {
+                writeScope: "workspace",
+                fields: [
+                    {
+                        key: "ANTHROPIC_API_KEY",
+                        label: "ANTHROPIC_API_KEY",
+                        placeholder: "sk-ant-...",
+                        secret: true,
+                    },
+                ],
+            },
+        },
+        {
+            id: "builder",
+            kind: "builder-cli-auth",
+            // TODO: expand scope to "llm" once the Builder LLM gateway ships so
+            // connecting Builder also provisions a managed model.
+            label: "Connect Builder",
+            description: "Unlocks LLM + browser automation + more. Free during beta.",
+            badge: "free",
+            payload: { scope: "browser" },
+        },
+    ],
+    isComplete: () => !!process.env.ANTHROPIC_API_KEY || !!process.env.BUILDER_PRIVATE_KEY,
+};
+/** Step 2 — where application data lives. SQLite default means non-blocking. */
+const databaseStep = {
+    id: "database",
+    order: 20,
+    required: false,
+    title: "Database",
+    description: "Where your app data lives.",
+    methods: [
+        {
+            id: "sqlite-default",
+            kind: "link",
+            label: "Use SQLite (default)",
+            description: "Zero setup, local dev only.",
+            primary: true,
+            payload: { url: "#" },
+        },
+        {
+            id: "postgres-url",
+            kind: "form",
+            label: "Use Postgres / Neon",
+            description: "Paste a DATABASE_URL for any SQL-compatible provider.",
+            payload: {
+                writeScope: "workspace",
+                fields: [
+                    {
+                        key: "DATABASE_URL",
+                        label: "DATABASE_URL",
+                        placeholder: "postgres://user:pass@host/db",
+                    },
+                ],
+            },
+        },
+    ],
+    // SQLite default means this step is always satisfied — never blocks setup.
+    isComplete: () => true,
+};
+/** Step 3 — how users sign in. Dev-mode keeps solo local workflows easy. */
+const authStep = {
+    id: "auth",
+    order: 30,
+    required: false,
+    title: "Authentication",
+    description: "How users sign in. Dev mode is fine for local work.",
+    methods: [
+        {
+            id: "local-dev",
+            kind: "link",
+            label: "Use local mode (dev)",
+            description: "Solo dev with no login step.",
+            primary: true,
+            payload: { url: "#" },
+        },
+        {
+            id: "better-auth-google",
+            kind: "form",
+            label: "Sign in with Google",
+            description: "Paste Google OAuth credentials (client ID + secret).",
+            payload: {
+                writeScope: "workspace",
+                fields: [
+                    { key: "GOOGLE_CLIENT_ID", label: "GOOGLE_CLIENT_ID" },
+                    {
+                        key: "GOOGLE_CLIENT_SECRET",
+                        label: "GOOGLE_CLIENT_SECRET",
+                        secret: true,
+                    },
+                ],
+            },
+        },
+    ],
+    isComplete: () => {
+        if (process.env.AUTH_MODE === "local")
+            return true;
+        if (process.env.ACCESS_TOKEN || process.env.ACCESS_TOKENS)
+            return true;
+        return !!(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET);
+    },
+};
+/** Step 4 — where uploaded files (avatars, chat attachments) go. */
+const fileUploadStep = {
+    id: "file-upload",
+    order: 40,
+    required: false,
+    title: "File uploads",
+    description: "Where user-uploaded files live. SQL fallback works out of the box but isn't optimal for production.",
+    methods: [
+        {
+            id: "builder",
+            kind: "builder-cli-auth",
+            label: "Connect Builder.io",
+            description: "Uploads go to Builder's CDN. Free during beta.",
+            primary: true,
+            badge: "free",
+            payload: { scope: "browser" },
+        },
+        {
+            id: "custom-provider",
+            kind: "link",
+            label: "Use your own provider",
+            description: "Register a FileUploadProvider (S3, R2, etc.) that returns a URL.",
+            payload: { url: "https://www.builder.io/c/docs/upload-api" },
+        },
+    ],
+    isComplete: () => !!process.env.BUILDER_PRIVATE_KEY,
+};
+let registered = false;
+/** Idempotent. Safe to call from every plugin-mount call. */
+export function registerDefaultOnboardingSteps() {
+    if (registered)
+        return;
+    registered = true;
+    registerOnboardingStep(llmStep);
+    registerOnboardingStep(databaseStep);
+    registerOnboardingStep(authStep);
+    registerOnboardingStep(fileUploadStep);
+}
+//# sourceMappingURL=default-steps.js.map

package/dist/onboarding/default-steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-steps.js","sourceRoot":"","sources":["../../src/onboarding/default-steps.ts"],"names":[],"mappings":"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"}

package/dist/onboarding/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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";
+//# sourceMappingURL=index.d.ts.map

package/dist/onboarding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/onboarding/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5E,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/onboarding/index.js

@@ -0,0 +1,11 @@
+/**
+ * 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 { createOnboardingPlugin, defaultOnboardingPlugin, } from "./plugin.js";
+export { registerDefaultOnboardingSteps } from "./default-steps.js";
+//# sourceMappingURL=index.js.map

package/dist/onboarding/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/onboarding/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAQ5E,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GAExB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/onboarding/plugin.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
+export interface OnboardingPluginOptions {
+    /** Skip registering the built-in default steps (llm, database, auth). */
+    skipDefaultSteps?: boolean;
+}
+export declare function createOnboardingPlugin(options?: OnboardingPluginOptions): NitroPluginDef;
+/** Default plugin instance — mounted automatically when a template doesn't override. */
+export declare const defaultOnboardingPlugin: NitroPluginDef;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/onboarding/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/onboarding/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAM9D,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAsDD,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,uBAA4B,GACpC,cAAc,CAoHhB;AAED,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,EAAE,cAAyC,CAAC"}

package/dist/onboarding/plugin.js

@@ -0,0 +1,147 @@
+/**
+ * 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, setResponseStatus, } from "h3";
+import { awaitBootstrap, getH3App, } from "../server/framework-request-handler.js";
+import { appStateGet, appStatePut } from "../application-state/store.js";
+import { getSession } from "../server/auth.js";
+import { listOnboardingSteps } from "./registry.js";
+import { registerDefaultOnboardingSteps } from "./default-steps.js";
+const ONBOARDING_PREFIX = "/_agent-native/onboarding";
+const OVERRIDE_KEY_PREFIX = "onboarding:override:";
+const DISMISSED_KEY = "onboarding:dismissed";
+/** Resolve the session id to use for application-state scoping. */
+async function resolveSessionId(event) {
+    const session = await getSession(event);
+    if (!session)
+        return "local";
+    if (session.email === "local@localhost")
+        return "local";
+    return session.email;
+}
+async function hasOverride(sessionId, stepId) {
+    const val = await appStateGet(sessionId, `${OVERRIDE_KEY_PREFIX}${stepId}`);
+    return !!(val && val.complete);
+}
+/**
+ * Serialise every registered onboarding step (awaiting `isComplete()`).
+ * Honours the per-session "manual override" flag in application-state.
+ */
+async function serializeSteps(sessionId) {
+    const steps = listOnboardingSteps();
+    const out = [];
+    for (const step of steps) {
+        let complete = false;
+        try {
+            complete = (await step.isComplete()) === true;
+        }
+        catch {
+            complete = false;
+        }
+        if (!complete) {
+            complete = await hasOverride(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 allRequiredComplete(statuses) {
+    return statuses.filter((s) => s.required).every((s) => s.complete);
+}
+export function createOnboardingPlugin(options = {}) {
+    return async (nitroApp) => {
+        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) => {
+            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 sessionId = await resolveSessionId(event);
+                return serializeSteps(sessionId);
+            }
+            // 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 resolveSessionId(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) => {
+            if (getMethod(event) !== "POST") {
+                setResponseStatus(event, 405);
+                return { error: "Method not allowed" };
+            }
+            const sessionId = await resolveSessionId(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) => {
+            if (getMethod(event) !== "POST") {
+                setResponseStatus(event, 405);
+                return { error: "Method not allowed" };
+            }
+            const sessionId = await resolveSessionId(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) => {
+            if (getMethod(event) !== "GET") {
+                setResponseStatus(event, 405);
+                return { error: "Method not allowed" };
+            }
+            const sessionId = await resolveSessionId(event);
+            const value = await appStateGet(sessionId, DISMISSED_KEY);
+            const dismissed = !!(value && value.dismissed);
+            const statuses = await serializeSteps(sessionId);
+            return {
+                dismissed,
+                allComplete: allRequiredComplete(statuses),
+            };
+        }));
+    };
+}
+/** Default plugin instance — mounted automatically when a template doesn't override. */
+export const defaultOnboardingPlugin = createOnboardingPlugin();
+//# sourceMappingURL=plugin.js.map

package/dist/onboarding/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/onboarding/plugin.ts"],"names":[],"mappings":"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"}

package/dist/onboarding/registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * In-process registry of onboarding steps.
+ *
+ * Templates (or the framework itself) call `registerOnboardingStep` at module
+ * load time — typically from a server plugin. The onboarding HTTP routes read
+ * from this registry on every request so overrides and late-registered steps
+ * are picked up without a restart.
+ */
+import type { OnboardingStep } from "./types.js";
+/**
+ * Register (or override) an onboarding step.
+ *
+ * Subsequent registrations with the same `id` replace the previous definition
+ * — templates can override framework defaults this way.
+ */
+export declare function registerOnboardingStep(step: OnboardingStep): void;
+/**
+ * Return all registered onboarding steps, sorted by `order` ascending.
+ * Ties are broken by registration order (insertion order).
+ */
+export declare function listOnboardingSteps(): OnboardingStep[];
+/** Test helper — clears the registry between runs. Not part of the public API. */
+export declare function __resetOnboardingRegistry(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/onboarding/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/onboarding/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAcjE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAEtD;AAED,kFAAkF;AAClF,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/onboarding/registry.js

@@ -0,0 +1,40 @@
+/**
+ * In-process registry of onboarding steps.
+ *
+ * Templates (or the framework itself) call `registerOnboardingStep` at module
+ * load time — typically from a server plugin. The onboarding HTTP routes read
+ * from this registry on every request so overrides and late-registered steps
+ * are picked up without a restart.
+ */
+const steps = new Map();
+/**
+ * Register (or override) an onboarding step.
+ *
+ * Subsequent registrations with the same `id` replace the previous definition
+ * — templates can override framework defaults this way.
+ */
+export function registerOnboardingStep(step) {
+    if (!step || typeof step.id !== "string" || !step.id) {
+        throw new Error("registerOnboardingStep: step.id is required");
+    }
+    if (steps.has(step.id)) {
+        // Override intentionally supported. Log only when DEBUG is on so template
+        // authors who deliberately override defaults don't see warnings.
+        if (process.env.DEBUG) {
+            console.log(`[agent-native] Overriding onboarding step "${step.id}" with new registration.`);
+        }
+    }
+    steps.set(step.id, step);
+}
+/**
+ * Return all registered onboarding steps, sorted by `order` ascending.
+ * Ties are broken by registration order (insertion order).
+ */
+export function listOnboardingSteps() {
+    return Array.from(steps.values()).sort((a, b) => a.order - b.order);
+}
+/** Test helper — clears the registry between runs. Not part of the public API. */
+export function __resetOnboardingRegistry() {
+    steps.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/onboarding/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/onboarding/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAoB;IACzD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACvB,0EAA0E;QAC1E,iEAAiE;QACjE,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CACT,8CAA8C,IAAI,CAAC,EAAE,0BAA0B,CAChF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,yBAAyB;IACvC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC"}

package/dist/onboarding/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Framework-level onboarding types.
+ *
+ * The onboarding system exposes a registry of "setup steps" that the agent
+ * sidebar renders as a checklist. Each step declares one or more `methods`
+ * by which the user can complete it (paste an API key, connect Builder, ask
+ * the agent to do it, etc.).
+ */
+export type OnboardingMethodBadge = "recommended" | "beta" | "free";
+/** Fields for a form-style onboarding method (key/value env-var entry). */
+export interface OnboardingFormField {
+    key: string;
+    label: string;
+    placeholder?: string;
+    secret?: boolean;
+}
+export interface OnboardingMethodBase {
+    id: string;
+    label: string;
+    description?: string;
+    badge?: OnboardingMethodBadge;
+    /** Highlight as the primary CTA for this step. */
+    primary?: boolean;
+}
+export type OnboardingMethod = (OnboardingMethodBase & {
+    kind: "link";
+    payload: {
+        url: string;
+        external?: boolean;
+    };
+}) | (OnboardingMethodBase & {
+    kind: "form";
+    payload: {
+        fields: OnboardingFormField[];
+        writeScope?: "workspace" | "app";
+    };
+}) | (OnboardingMethodBase & {
+    kind: "builder-cli-auth";
+    payload: {
+        scope: "browser";
+    };
+}) | (OnboardingMethodBase & {
+    kind: "agent-task";
+    payload: {
+        prompt: string;
+    };
+});
+export interface OnboardingStep {
+    /** Stable ID (e.g. "llm", "gmail"). */
+    id: string;
+    title: string;
+    description: string;
+    /** Lower = earlier. Default order slots: 10 (engine), 20 (db), 30 (auth). */
+    order: number;
+    /** Required steps block onboarding dismissal when incomplete. */
+    required?: boolean;
+    methods: OnboardingMethod[];
+    /** Resolver — called on every `GET /_agent-native/onboarding/steps` request. */
+    isComplete: () => boolean | Promise<boolean>;
+}
+/** Serialized shape returned by `GET /_agent-native/onboarding/steps`. */
+export interface OnboardingStepStatus {
+    id: string;
+    title: string;
+    description: string;
+    order: number;
+    required: boolean;
+    complete: boolean;
+    methods: OnboardingMethod[];
+}
+//# sourceMappingURL=types.d.ts.map