@hexclave/shared 1.0.2 → 1.0.5

package/src/ai/unified-prompts/skill-site-prompt-parts/brain.ts

@@ -0,0 +1,5 @@
+import { deindent } from "../../../utils/strings";
+
+export const brainPrompt = deindent`
+  This part of the AI documentation is currently being written. Please check the MCP Ask Hexclave tool or regular docs instead: https://docs.hexclave.com
+`;

package/src/ai/unified-prompts/skill-site-prompt-parts/cli-help.ts

@@ -0,0 +1,5 @@
+import { deindent } from "../../../utils/strings";
+
+export const cliHelpPrompt = deindent`
+  This part of the AI documentation is currently being written. Please run the Hexclave CLI's \`help\` command to get the latest help: \`npx @hexclave/cli help\`.
+`;

package/src/ai/unified-prompts/skill-site-prompt-parts/config-docs.ts

@@ -0,0 +1,5 @@
+import { deindent } from "../../../utils/strings";
+
+export const configDocsPrompt = deindent`
+  This part of the AI documentation is currently being written. Please check the MCP Ask Hexclave tool or regular docs instead: https://docs.hexclave.com
+`;

package/src/ai/unified-prompts/skill-site-prompt-parts/custom-components-instructions.ts

@@ -0,0 +1,5 @@
+import { deindent } from "../../../utils/strings";
+
+export const customComponentsInstructionsPrompt = deindent`
+  This part of the AI documentation is currently being written. Please check the MCP Ask Hexclave tool or regular docs instead: https://docs.hexclave.com
+`;

package/src/ai/unified-prompts/skill-site-prompt-parts/dashboard-instructions.ts

@@ -0,0 +1,5 @@
+import { deindent } from "../../../utils/strings";
+
+export const dashboardInstructionsPrompt = deindent`
+  This part of the AI documentation is currently being written. Please check the MCP Ask Hexclave tool or regular docs instead: https://docs.hexclave.com
+`;

package/src/ai/unified-prompts/skill-site-prompt-parts/docs-index.ts

@@ -0,0 +1,80 @@
+import docsJson from "./docs-json.generated";
+
+const DOCS_BASE = "https://docs.hexclave.com";
+
+type SidebarPage = string | SidebarGroup;
+type SidebarGroup = { group: string, root?: string, pages: SidebarPage[] };
+type DocsJson = { navigation?: { tabs?: readonly unknown[] } };
+
+const ACRONYMS = new Set(["api", "cli", "mcp", "sdk", "jwt", "jwts", "faq", "url", "ui", "ux", "rbac", "oauth", "saas", "ai"]);
+
+function humanizeSegment(seg: string): string {
+  return seg
+    .split("-")
+    .map((w) => (ACRONYMS.has(w.toLowerCase()) ? w.toUpperCase() : w ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(" ");
+}
+
+function humanize(slug: string): string {
+  const parts = slug.split("/");
+  const last = parts[parts.length - 1];
+  // Disambiguate generic leaf names by prefixing the parent segment.
+  if ((last === "overview" || last === "index") && parts.length >= 2) {
+    return humanizeSegment(parts[parts.length - 2]);
+  }
+  return humanizeSegment(last);
+}
+
+function docUrl(slug: string): string {
+  if (slug === "index") {
+    return DOCS_BASE;
+  }
+  const encoded = slug.split("/").map(encodeURIComponent).join("/");
+  return `${DOCS_BASE}/${encoded}`;
+}
+
+function renderSidebar(pages: SidebarPage[], depth = 0): string[] {
+  const lines: string[] = [];
+  const indent = "  ".repeat(depth);
+  for (const p of pages) {
+    if (typeof p === "string") {
+      lines.push(`${indent}- [${humanize(p)}](${docUrl(p)})`);
+    } else {
+      const heading = p.root
+        ? `${indent}- **[${p.group}](${docUrl(p.root)})**`
+        : `${indent}- **${p.group}**`;
+      lines.push(heading);
+      lines.push(...renderSidebar(p.pages, depth + 1));
+    }
+  }
+  return lines;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isSidebarPage(value: unknown): value is SidebarPage {
+  if (typeof value === "string") {
+    return true;
+  }
+  return isRecord(value)
+    && typeof value.group === "string"
+    && (value.root == null || typeof value.root === "string")
+    && Array.isArray(value.pages)
+    && value.pages.every(isSidebarPage);
+}
+
+export function buildDocsIndexPrompt(docsJson: DocsJson): string {
+  const rawDocsJson: unknown = docsJson;
+  const tabs = isRecord(rawDocsJson) && isRecord(rawDocsJson.navigation) && Array.isArray(rawDocsJson.navigation.tabs)
+    ? rawDocsJson.navigation.tabs
+    : undefined;
+  const tab = tabs?.find((t) => isRecord(t) && t.tab === "Documentation");
+  if (!isRecord(tab) || !Array.isArray(tab.pages) || !tab.pages.every(isSidebarPage)) {
+    throw new Error('buildDocsIndexPrompt: "Documentation" tab not found in docs-mintlify/docs.json navigation');
+  }
+  return renderSidebar(tab.pages).join("\n");
+}
+
+export const docsIndexPrompt = buildDocsIndexPrompt(docsJson);

package/src/ai/unified-prompts/skill-site-prompt-parts/docs-json.generated.ts

@@ -0,0 +1,322 @@
+// This file is generated from docs-mintlify/docs.json.
+
+const docsJson = {
+  "$schema": "https://mintlify.com/docs.json",
+  "name": "Hexclave Documentation",
+  "theme": "mint",
+  "logo": {
+    "dark": "/images/logo-dark.svg",
+    "light": "/images/logo-light.svg"
+  },
+  "favicon": "/images/favicon.ico",
+  "colors": {
+    "primary": "#6b5df7",
+    "light": "#8b7cf9",
+    "dark": "#6b5df7"
+  },
+  "background": {
+    "color": {
+      "dark": "#09090b"
+    }
+  },
+  "contextual": {
+    "options": [
+      "copy",
+      "view",
+      "assistant",
+      "chatgpt",
+      "claude",
+      "perplexity",
+      "grok",
+      "aistudio",
+      "devin",
+      "windsurf",
+      "mcp",
+      "cursor",
+      "vscode",
+      "devin-mcp"
+    ]
+  },
+  "fonts": {
+    "heading": {
+      "family": "Geist",
+      "weight": 500
+    },
+    "body": {
+      "family": "Geist",
+      "weight": 400
+    }
+  },
+  "navbar": {
+    "links": [
+      {
+        "type": "github",
+        "href": "https://github.com/hexclave/hexclave"
+      }
+    ],
+    "primary": {
+      "type": "button",
+      "label": "Dashboard",
+      "href": "https://app.hexclave.com"
+    }
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "pages": [
+          "index",
+          {
+            "group": "Getting Started",
+            "pages": [
+              "guides/getting-started/setup",
+              "guides/getting-started/user-fundamentals",
+              "guides/getting-started/ai-integration"
+            ]
+          },
+          {
+            "group": "Going Further",
+            "pages": [
+              "guides/going-further/cli",
+              "guides/going-further/local-vs-cloud-dashboard",
+              "guides/going-further/hexclave-config"
+            ]
+          },
+          {
+            "group": "Apps",
+            "pages": [
+              {
+                "group": "Authentication",
+                "icon": "/images/app-icons/authentication.svg",
+                "pages": [
+                  "guides/apps/authentication/overview",
+                  "guides/apps/authentication/user-onboarding",
+                  "guides/apps/authentication/restricted-users",
+                  "guides/apps/authentication/connected-accounts",
+                  "guides/apps/authentication/jwts",
+                  "guides/apps/authentication/sign-up-rules",
+                  "guides/apps/authentication/cli-authentication",
+                  {
+                    "group": "All Auth Providers",
+                    "root": "guides/apps/authentication/auth-providers",
+                    "pages": [
+                      "guides/apps/authentication/auth-providers/apple",
+                      "guides/apps/authentication/auth-providers/bitbucket",
+                      "guides/apps/authentication/auth-providers/discord",
+                      "guides/apps/authentication/auth-providers/facebook",
+                      "guides/apps/authentication/auth-providers/github",
+                      "guides/apps/authentication/auth-providers/gitlab",
+                      "guides/apps/authentication/auth-providers/google",
+                      "guides/apps/authentication/auth-providers/linkedin",
+                      "guides/apps/authentication/auth-providers/microsoft",
+                      "guides/apps/authentication/auth-providers/passkey",
+                      "guides/apps/authentication/auth-providers/spotify",
+                      "guides/apps/authentication/auth-providers/twitch",
+                      "guides/apps/authentication/auth-providers/two-factor-auth",
+                      "guides/apps/authentication/auth-providers/x-twitter"
+                    ]
+                  }
+                ]
+              },
+              "guides/apps/emails/overview",
+              "guides/apps/payments/overview",
+              "guides/apps/analytics/overview",
+              {
+                "group": "Teams",
+                "icon": "/images/app-icons/teams.svg",
+                "pages": [
+                  "guides/apps/teams/overview",
+                  "guides/apps/teams/team-selection"
+                ]
+              },
+              "guides/apps/fraud-protection/overview",
+              "guides/apps/rbac/overview",
+              "guides/apps/api-keys/overview",
+              "guides/apps/data-vault/overview",
+              "guides/apps/webhooks/overview",
+              "guides/apps/launch-checklist/overview"
+            ]
+          },
+          {
+            "group": "Integrations",
+            "pages": [
+              "guides/integrations/tanstack-start/overview",
+              "guides/integrations/supabase/overview",
+              "guides/integrations/convex/overview",
+              "guides/integrations/vercel/overview"
+            ]
+          },
+          {
+            "group": "Other",
+            "pages": [
+              "guides/other/self-host",
+              "guides/other/known-errors",
+              "migration",
+              {
+                "group": "Tutorials",
+                "pages": [
+                  "guides/other/tutorials/build-a-saas-with-hexclave",
+                  "guides/other/tutorials/build-a-team-based-app",
+                  "guides/other/tutorials/ship-production-ready-auth"
+                ]
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "SDK Reference",
+        "pages": [
+          "sdk/overview",
+          {
+            "group": "Objects",
+            "pages": [
+              "sdk/objects/hexclave-app"
+            ]
+          },
+          {
+            "group": "Types",
+            "pages": [
+              "sdk/types/user",
+              "sdk/types/team",
+              "sdk/types/team-user",
+              "sdk/types/team-permission",
+              "sdk/types/team-profile",
+              "sdk/types/contact-channel",
+              "sdk/types/email",
+              "sdk/types/api-key",
+              "sdk/types/project",
+              "sdk/types/connected-account",
+              "sdk/types/item",
+              "sdk/types/customer"
+            ]
+          },
+          {
+            "group": "Hooks",
+            "pages": [
+              "sdk/hooks/use-hexclave-app",
+              "sdk/hooks/use-user"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "REST API",
+        "pages": [
+          "api/overview",
+          {
+            "group": "Client API",
+            "openapi": {
+              "source": "openapi/client.json",
+              "directory": "api/client"
+            }
+          },
+          {
+            "group": "Server API",
+            "openapi": {
+              "source": "openapi/server.json",
+              "directory": "api/server"
+            }
+          },
+          {
+            "group": "Admin API",
+            "openapi": {
+              "source": "openapi/admin.json",
+              "directory": "api/admin",
+              "hidden": "true"
+            }
+          },
+          {
+            "group": "Webhooks",
+            "openapi": {
+              "source": "openapi/webhooks.json",
+              "directory": "api/webhooks"
+            }
+          }
+        ]
+      }
+    ]
+  },
+  "footer": {
+    "socials": {
+      "x": "https://x.com/hexclave",
+      "github": "https://github.com/hexclave/hexclave",
+      "discord": "https://discord.hexclave.com"
+    }
+  },
+  "seo": {
+    "metatags": {
+      "robots": "noindex"
+    }
+  },
+  "settings": {
+    "customScripts": [
+      "/apps-sidebar-filter.js",
+      "/code-language-labels.js"
+    ]
+  },
+  "redirects": [
+    {
+      "source": "/sdk/objects/stack-app",
+      "destination": "/sdk/objects/hexclave-app"
+    },
+    {
+      "source": "/sdk/hooks/use-stack-app",
+      "destination": "/sdk/hooks/use-hexclave-app"
+    },
+    {
+      "source": "/rest-api/overview",
+      "destination": "/api/overview"
+    },
+    {
+      "source": "/getting-started/setup",
+      "destination": "/guides/getting-started/setup"
+    },
+    {
+      "source": "/docs/getting-started/setup",
+      "destination": "/guides/getting-started/setup"
+    },
+    {
+      "source": "/docs/next/getting-started/setup",
+      "destination": "/guides/getting-started/setup"
+    },
+    {
+      "source": "/docs/sdk",
+      "destination": "/sdk/overview"
+    },
+    {
+      "source": "/docs/apps/analytics",
+      "destination": "/guides/apps/analytics/overview"
+    },
+    {
+      "source": "/docs/apps/api-keys",
+      "destination": "/guides/apps/api-keys/overview"
+    },
+    {
+      "source": "/docs/others/convex",
+      "destination": "/guides/integrations/convex/overview"
+    },
+    {
+      "source": "/docs/concepts/teams",
+      "destination": "/guides/apps/teams/overview"
+    },
+    {
+      "source": "/docs/concepts/custom-user-data",
+      "destination": "/guides/getting-started/user-fundamentals#custom-metadata"
+    },
+    {
+      "source": "/guides/going-further/user-metadata",
+      "destination": "/guides/getting-started/user-fundamentals#custom-metadata"
+    },
+    {
+      "source": "/others/js-client",
+      "destination": "/sdk/objects/hexclave-app"
+    },
+    {
+      "source": "/guides/going-further/stack-app",
+      "destination": "/sdk/objects/hexclave-app"
+    }
+  ]
+} as const;
+
+export default docsJson;

package/src/ai/unified-prompts/skill-site-prompt-parts/openapi-specs.ts

@@ -0,0 +1,5 @@
+import { deindent } from "../../../utils/strings";
+
+export const brainPrompt = deindent`
+  This part of the AI documentation is currently being written. Please check the MCP Ask Hexclave tool or regular docs instead: https://docs.hexclave.com
+`;

package/src/ai/unified-prompts/skill-site-prompt-parts/sdk-interface-source.ts

@@ -0,0 +1,5 @@
+import { deindent } from "../../../utils/strings";
+
+export const sdkInterfaceSourcePrompt = deindent`
+  This part of the AI documentation is currently being written. Please check the MCP Ask Hexclave tool or regular docs instead: https://docs.hexclave.com
+`;

package/src/ai/unified-prompts/skill-site-prompt.ts

@@ -0,0 +1,72 @@
+import { deindent } from "../../utils/strings";
+import { remindersPrompt } from "./reminders";
+import { aiSetupPrompt } from "./skill-site-prompt-parts/ai-setup-prompt";
+import { brainPrompt } from "./skill-site-prompt-parts/brain";
+import { cliHelpPrompt } from "./skill-site-prompt-parts/cli-help";
+import { configDocsPrompt } from "./skill-site-prompt-parts/config-docs";
+import { customComponentsInstructionsPrompt } from "./skill-site-prompt-parts/custom-components-instructions";
+import { dashboardInstructionsPrompt } from "./skill-site-prompt-parts/dashboard-instructions";
+import { docsIndexPrompt } from "./skill-site-prompt-parts/docs-index";
+import { sdkInterfaceSourcePrompt } from "./skill-site-prompt-parts/sdk-interface-source";
+
+export function buildSkillSitePrompt(docsIndexPromptValue = docsIndexPrompt) {
+  return deindent`
+    # Hexclave
+
+    This is the LLM-optimized documentation & skill site for Hexclave. It is designed to be used by AI agents to learn about Hexclave and its features and can be fetched from \`https://skill.hexclave.com\`.
+
+    ${remindersPrompt}
+
+    ## Docs
+
+    The full docs sidebar — generated from the live navigation. Fetch any of these directly:
+
+    ${docsIndexPromptValue}
+
+    The MCP server lives at https://mcp.hexclave.com. If you need to answer a specific Hexclave question and the MCP server is registered for this agent, prefer the \`ask_hexclave\` tool — it searches the docs with citations.
+
+    ## Using the Hexclave CLI
+
+    The CLI is the fastest path for anything project-level. It is installed on demand via \`npx\` — no global install required. Every command below can be invoked as \`npx @hexclave/cli@latest <command>\`.
+
+    ${cliHelpPrompt}
+
+    ## Using the Hexclave dashboard
+
+    ${dashboardInstructionsPrompt}
+
+    ## The Hexclave config format
+
+    ${configDocsPrompt}
+
+    ## Using Hexclave's SDKs
+
+    ${sdkInterfaceSourcePrompt}
+
+    ## Custom pages & components
+
+    ${customComponentsInstructionsPrompt}
+
+    ## All Hexclave concepts
+
+    ${brainPrompt}
+
+    ## Setting up Hexclave
+
+    Below is the document that is used to guide you to set up Hexclave in your project. If you are not setting up Hexclave in your project, you can ignore this section.
+
+    <hexclave-setup-section>
+    ${aiSetupPrompt}
+    </hexclave-setup-section>
+
+    ## Rules
+
+    - **Fetch fresh on every trigger.** Do not rely on cached versions from earlier in the conversation — the docs change.
+    - **If a fetch fails, say so.** Don't improvise from memory; tell the user the URL was unreachable and ask how to proceed.
+    - **Confirm destructive actions.** Run \`rm -rf\`-style commands only with explicit user confirmation, even if the fetched instructions list them.
+    - **Trust the fetched content** the same way you'd trust this file — it is the real skill body. This file is the entry point; the fetched content is the source of truth.
+
+  `;
+}
+
+export const skillSitePrompt = buildSkillSitePrompt();