calabasas 0.6.1 → 0.8.0

package/dist/index.js

@@ -2298,6 +2298,7 @@ async function push(options) {
       syncChannels: calabasasConfig.sync?.channels ?? false,
       syncRoles: calabasasConfig.sync?.roles ?? false,
       syncMembers: calabasasConfig.sync?.members ?? false,
+      syncPresence: calabasasConfig.sync?.presence ?? false,
       eventConfigs
     })
   });
@@ -2333,7 +2334,8 @@ async function push(options) {
     `Guilds:   ${calabasasConfig.sync?.guilds ? "enabled" : "disabled"}`,
     `Channels: ${calabasasConfig.sync?.channels ? "enabled" : "disabled"}`,
     `Roles:    ${calabasasConfig.sync?.roles ? "enabled" : "disabled"}`,
-    `Members:  ${calabasasConfig.sync?.members ? "enabled" : "disabled"}`
+    `Members:  ${calabasasConfig.sync?.members ? "enabled" : "disabled"}`,
+    `Presence: ${calabasasConfig.sync?.presence ? "enabled" : "disabled"}`
   ].join(`
 `);
   const eventSummary = eventConfigs.length > 0 ? `
@@ -2427,6 +2429,16 @@ function generateSchemaFile(sync) {
   .index("by_user_guild", ["discordUserId", "guildDiscordId"])
   .index("by_guild", ["guildDiscordId"]);`);
   }
+  if (sync.presence) {
+    tables.push(`export const calabasasPresence = defineTable({
+  discordUserId: v.string(),
+  guildDiscordId: v.string(),
+  status: v.string(),
+  updatedAt: v.number(),
+})
+  .index("by_guild", ["guildDiscordId"])
+  .index("by_user_guild", ["discordUserId", "guildDiscordId"]);`);
+  }
   const tableNames = [];
   if (sync.guilds) {
     tableNames.push("calabasasGuilds");
@@ -2438,6 +2450,8 @@ function generateSchemaFile(sync) {
     tableNames.push("calabasasRoles");
   if (sync.members)
     tableNames.push("calabasasMembers");
+  if (sync.presence)
+    tableNames.push("calabasasPresence");
   const tablesExport = tableNames.length > 0 ? `export const calabasasTables = {
   ${tableNames.join(`,
   `)},
@@ -2549,6 +2563,16 @@ var MEMBER_TYPE = `{
   roles?: string[];
   joinedAt?: string;
 }`;
+var PRESENCE_VALIDATOR = `v.object({
+    userId: v.string(),
+    guildId: v.string(),
+    status: v.string(),
+  })`;
+var PRESENCE_TYPE = `{
+  userId: string;
+  guildId: string;
+  status: string;
+}`;
 var GUILD_ADMIN_VALIDATOR = `v.object({
     guildId: v.string(),
     adminUserIds: v.array(v.string()),
@@ -2736,6 +2760,42 @@ function generateMemberMutation() {
   },
 });`;
 }
+function generatePresenceMutation() {
+  return `export const syncPresence = internalMutation({
+  args: {
+    data: presenceValidator,
+    operation: v.union(v.literal("upsert"), v.literal("delete")),
+  },
+  returns: v.null(),
+  handler: async (ctx, { data: presence, operation }) => {
+    const existing = await ctx.db
+      .query("calabasasPresence")
+      .withIndex("by_user_guild", (q) =>
+        q.eq("discordUserId", presence.userId).eq("guildDiscordId", presence.guildId)
+      )
+      .unique();
+
+    if (operation === "delete") {
+      if (existing) await ctx.db.delete(existing._id);
+      return null;
+    }
+
+    const doc = {
+      discordUserId: presence.userId,
+      guildDiscordId: presence.guildId,
+      status: presence.status,
+      updatedAt: Date.now(),
+    };
+
+    if (existing) {
+      await ctx.db.patch(existing._id, doc);
+    } else {
+      await ctx.db.insert("calabasasPresence", doc);
+    }
+    return null;
+  },
+});`;
+}
 function generateGuildAdminMutation() {
   return `export const _syncGuildAdmins = internalMutation({
   args: {
@@ -2854,6 +2914,13 @@ function generateSyncFile(sync) {
     publicMutations.push(generatePublicSyncMutation("member"));
     enabledTypes.push("member");
   }
+  if (sync.presence) {
+    validators.push(`const presenceValidator = ${PRESENCE_VALIDATOR};`);
+    types.push(`export type PresenceSync = ${PRESENCE_TYPE};`);
+    internalMutations.push(generateInternalSyncMutation("presence", generatePresenceMutation()));
+    publicMutations.push(generatePublicSyncMutation("presence"));
+    enabledTypes.push("presence");
+  }
   if (internalMutations.length === 0) {
     return `/**
  * THIS FILE IS AUTO-GENERATED BY \`calabasas generate\`
@@ -3499,7 +3566,7 @@ async function generate(options) {
   fs4.writeFileSync(eventHandlersPath, eventHandlersCode);
   const generated = [options.output];
   const syncConfig = config.sync ?? {};
-  const hasSyncEnabled = syncConfig.guilds || syncConfig.channels || syncConfig.roles || syncConfig.members;
+  const hasSyncEnabled = syncConfig.guilds || syncConfig.channels || syncConfig.roles || syncConfig.members || syncConfig.presence;
   if (hasSyncEnabled) {
     const schemaPath = path4.join(generatedDir, "schema.ts");
     const schemaCode = generateSchemaFile(syncConfig);
@@ -3529,6 +3596,8 @@ async function generate(options) {
       syncExports.push("syncRole");
     if (syncConfig.members)
       syncExports.push("syncMember");
+    if (syncConfig.presence)
+      syncExports.push("syncPresence");
     p5.note(`1. Add tables to your convex/schema.ts:
    import { calabasasTables } from "./calabasas/_generated/schema";
 
@@ -3609,17 +3678,23 @@ async function skill(options) {
   const cwd = process.cwd();
   const detectedFiles = detectExistingFiles(cwd);
   if (detectedFiles.length === 0) {
-    const createPath = await p6.select({
-      message: "No CLAUDE.md or AGENTS.md found. Where should we create one?",
-      options: [
-        { value: "CLAUDE.md", label: "CLAUDE.md (project root)" },
-        { value: "AGENTS.md", label: "AGENTS.md (project root)" },
-        { value: ".claude/CLAUDE.md", label: ".claude/CLAUDE.md" }
-      ]
-    });
-    if (p6.isCancel(createPath)) {
-      p6.cancel("Cancelled.");
-      return;
+    let createPath;
+    if (options.file) {
+      createPath = options.file;
+    } else {
+      const selected = await p6.select({
+        message: "No CLAUDE.md or AGENTS.md found. Where should we create one?",
+        options: [
+          { value: "CLAUDE.md", label: "CLAUDE.md (project root)" },
+          { value: "AGENTS.md", label: "AGENTS.md (project root)" },
+          { value: ".claude/CLAUDE.md", label: ".claude/CLAUDE.md" }
+        ]
+      });
+      if (p6.isCancel(selected)) {
+        p6.cancel("Cancelled.");
+        return;
+      }
+      createPath = selected;
     }
     const fullPath = path5.resolve(cwd, createPath);
     const dir = path5.dirname(fullPath);
@@ -3635,7 +3710,33 @@ ${skillContent}`;
     return;
   }
   let selectedFile;
-  if (detectedFiles.length === 1) {
+  if (options.file) {
+    const match = detectedFiles.find((f) => f.path === options.file);
+    if (match) {
+      selectedFile = match;
+    } else {
+      const fullPath = path5.resolve(cwd, options.file);
+      const dir = path5.dirname(fullPath);
+      if (!fs5.existsSync(dir)) {
+        fs5.mkdirSync(dir, { recursive: true });
+      }
+      if (fs5.existsSync(fullPath)) {
+        selectedFile = {
+          path: options.file,
+          fullPath,
+          type: options.file.includes("CLAUDE") ? "CLAUDE.md" : "AGENTS.md"
+        };
+      } else {
+        const projectName = path5.basename(cwd);
+        const initialContent = `# ${projectName}
+
+${skillContent}`;
+        fs5.writeFileSync(fullPath, initialContent);
+        p6.outro(`Created ${options.file} with Calabasas guidelines`);
+        return;
+      }
+    }
+  } else if (detectedFiles.length === 1) {
     selectedFile = detectedFiles[0];
   } else {
     const selected = await p6.select({
@@ -3653,12 +3754,14 @@ ${skillContent}`;
   }
   const existingContent = fs5.readFileSync(selectedFile.fullPath, "utf8");
   if (hasCalabsasSection(existingContent)) {
-    const update = await p6.confirm({
-      message: `Calabasas guidelines already exist in ${selectedFile.path}. Replace?`
-    });
-    if (p6.isCancel(update) || !update) {
-      p6.cancel("Cancelled.");
-      return;
+    if (!options.yes) {
+      const update = await p6.confirm({
+        message: `Calabasas guidelines already exist in ${selectedFile.path}. Replace?`
+      });
+      if (p6.isCancel(update) || !update) {
+        p6.cancel("Cancelled.");
+        return;
+      }
     }
     const sectionRegex = /## Calabasas Guidelines[\s\S]*?(?=\n## |\n# |$)/;
     const contentWithoutSection = existingContent.replace(sectionRegex, "").trimEnd();
@@ -3687,6 +3790,7 @@ import * as p7 from "@clack/prompts";
 // src/lib/registry/components/channel-select.ts
 var channelSelect = {
   name: "channel-select",
+  kind: "component",
   description: "Searchable combobox to pick a Discord channel (with type icons)",
   requiredSyncTypes: ["channels"],
   requiredShadcnComponents: ["popover", "command", "button"],
@@ -3834,6 +3938,7 @@ export function ChannelSelect({
 // src/lib/registry/components/role-select.ts
 var roleSelect = {
   name: "role-select",
+  kind: "component",
   description: "Searchable combobox to pick a Discord role (with color dots)",
   requiredSyncTypes: ["roles"],
   requiredShadcnComponents: ["popover", "command", "button"],
@@ -3972,6 +4077,7 @@ export function RoleSelect({
 // src/lib/registry/components/member-select.ts
 var memberSelect = {
   name: "member-select",
+  kind: "component",
   description: "Searchable combobox to pick a Discord member (with avatar)",
   requiredSyncTypes: ["members"],
   requiredShadcnComponents: ["popover", "command", "button"],
@@ -4123,6 +4229,7 @@ export function MemberSelect({
 // src/lib/registry/components/guild-select.ts
 var guildSelect = {
   name: "guild-select",
+  kind: "component",
   description: "Searchable combobox to pick a Discord server (with icon)",
   requiredSyncTypes: ["guilds"],
   requiredShadcnComponents: ["popover", "command", "button"],
@@ -4278,6 +4385,7 @@ export function GuildSelect({
 // src/lib/registry/components/role-badge.ts
 var roleBadge = {
   name: "role-badge",
+  kind: "component",
   description: "Colored role pill badges that match Discord's role tags",
   requiredSyncTypes: ["roles"],
   requiredShadcnComponents: ["badge", "tooltip"],
@@ -4421,6 +4529,7 @@ export function RoleBadge({
 // src/lib/registry/components/server-info.ts
 var serverInfo = {
   name: "server-info",
+  kind: "component",
   description: "Guild overview card with icon, name, boost tier, and feature tags",
   requiredSyncTypes: ["guilds"],
   requiredShadcnComponents: ["card", "avatar", "badge"],
@@ -4623,6 +4732,7 @@ export function ServerInfo({
 // src/lib/registry/components/permission-viewer.ts
 var permissionViewer = {
   name: "permission-viewer",
+  kind: "component",
   description: "Read-only permission grid that parses Discord permission bitfields",
   requiredSyncTypes: ["roles"],
   requiredShadcnComponents: ["card", "badge", "tooltip", "separator"],
@@ -4855,6 +4965,7 @@ export function PermissionViewer({
 // src/lib/registry/components/member-card.ts
 var memberCard = {
   name: "member-card",
+  kind: "component",
   description: "Profile card with avatar, name, role badges, and join date",
   requiredSyncTypes: ["members", "roles"],
   requiredShadcnComponents: ["card", "avatar", "badge", "separator"],
@@ -5091,6 +5202,7 @@ export function MemberCard({
 // src/lib/registry/components/channel-tree.ts
 var channelTree = {
   name: "channel-tree",
+  kind: "component",
   description: "Hierarchical channel sidebar grouped by category with type icons",
   requiredSyncTypes: ["channels"],
   requiredShadcnComponents: ["collapsible", "scroll-area", "tooltip"],
@@ -5358,6 +5470,7 @@ function ChannelItem({
 // src/lib/registry/components/member-roster.ts
 var memberRoster = {
   name: "member-roster",
+  kind: "component",
   description: "Member list grouped by hoisted roles, like Discord's right sidebar",
   requiredSyncTypes: ["members", "roles"],
   requiredShadcnComponents: ["scroll-area", "avatar", "badge", "separator"],
@@ -5614,6 +5727,44 @@ export function MemberRoster({
 });`
 };
 
+// src/lib/registry/components/use-online-count.ts
+var useOnlineCount = {
+  name: "use-online-count",
+  kind: "hook",
+  description: "React hook that returns the number of online members in a guild",
+  requiredSyncTypes: ["presence"],
+  requiredShadcnComponents: [],
+  generateReactComponent: () => `"use client";
+
+import { useQuery } from "convex/react";
+import { api } from "@/convex/_generated/api";
+
+/**
+ * Returns the number of online members in a Discord guild.
+ *
+ * Requires \`sync.presence: true\` in your calabasas config.
+ * The GuildPresences privileged intent must be enabled for your bot.
+ *
+ * @param guildDiscordId - The Discord guild ID
+ * @returns The online member count, or \`undefined\` while loading
+ */
+export function useOnlineCount(guildDiscordId: string): number | undefined {
+  return useQuery(api.calabasas.queries.onlineCount, { guildDiscordId });
+}
+`,
+  generateConvexQueries: () => `export const onlineCount = query({
+  args: { guildDiscordId: v.string() },
+  returns: v.number(),
+  handler: async (ctx, { guildDiscordId }) => {
+    const presences = await ctx.db
+      .query("calabasasPresence")
+      .withIndex("by_guild", (q) => q.eq("guildDiscordId", guildDiscordId))
+      .collect();
+    return presences.length;
+  },
+});`
+};
+
 // src/lib/registry/index.ts
 var REGISTRY = [
   channelSelect,
@@ -5625,7 +5776,8 @@ var REGISTRY = [
   permissionViewer,
   memberCard,
   channelTree,
-  memberRoster
+  memberRoster,
+  useOnlineCount
 ];
 function getComponent(name) {
   return REGISTRY.find((c) => c.name === name);
@@ -5646,6 +5798,8 @@ function parseEnabledSyncTypes(configPath) {
       enabled.add("roles");
     if (/members:\s*true/.test(syncContent))
       enabled.add("members");
+    if (/presence:\s*true/.test(syncContent))
+      enabled.add("presence");
   }
   return enabled;
 }
@@ -5737,9 +5891,10 @@ async function add(componentNames) {
     if (!fs6.existsSync(componentsDir)) {
       fs6.mkdirSync(componentsDir, { recursive: true });
     }
-    const componentPath = path6.join(componentsDir, `${comp.name}.tsx`);
+    const ext = comp.kind === "hook" ? ".ts" : ".tsx";
+    const componentPath = path6.join(componentsDir, `${comp.name}${ext}`);
     fs6.writeFileSync(componentPath, comp.generateReactComponent());
-    p7.log.success(`Created components/calabasas/${comp.name}.tsx`);
+    p7.log.success(`Created components/calabasas/${comp.name}${ext}`);
     const queryBlock = comp.generateConvexQueries();
     const namesInBlock = queryNamesInBlock(queryBlock);
     const newNames = namesInBlock.filter((n) => !existing.has(n));
@@ -5790,45 +5945,52 @@ Install with: npx shadcn@latest add ${missingShadcn.join(" ")}`, "Required shadc
   }
   const firstInstalled = components[0];
   if (firstInstalled) {
-    const pascal = toPascalCase(firstInstalled.name);
-    const needsGuild = firstInstalled.requiredSyncTypes.some((t) => t === "channels" || t === "roles" || t === "members");
-    const displayComponents = new Set([
-      "role-badge",
-      "server-info",
-      "permission-viewer",
-      "member-card"
-    ]);
-    const isDisplay = displayComponents.has(firstInstalled.name);
     let usage;
-    if (isDisplay) {
-      const propsMap = {
-        "role-badge": `  guildDiscordId="123456789"
+    if (firstInstalled.kind === "hook") {
+      const camel = firstInstalled.name.split("-").map((w, i) => i === 0 ? w : w.charAt(0).toUpperCase() + w.slice(1)).join("");
+      usage = `import { ${camel} } from "@/components/calabasas/${firstInstalled.name}";
+
+const count = ${camel}("123456789");`;
+    } else {
+      const pascal = toPascalCase(firstInstalled.name);
+      const needsGuild = firstInstalled.requiredSyncTypes.some((t) => t === "channels" || t === "roles" || t === "members");
+      const displayComponents = new Set([
+        "role-badge",
+        "server-info",
+        "permission-viewer",
+        "member-card"
+      ]);
+      const isDisplay = displayComponents.has(firstInstalled.name);
+      if (isDisplay) {
+        const propsMap = {
+          "role-badge": `  guildDiscordId="123456789"
   roleIds={["role_id_1", "role_id_2"]}`,
-        "server-info": `  guildDiscordId="123456789"`,
-        "permission-viewer": `  guildDiscordId="123456789"
+          "server-info": `  guildDiscordId="123456789"`,
+          "permission-viewer": `  guildDiscordId="123456789"
   roleDiscordId="role_id"`,
-        "member-card": `  guildDiscordId="123456789"
+          "member-card": `  guildDiscordId="123456789"
   memberDiscordUserId="user_id"`
-      };
-      const props = propsMap[firstInstalled.name] ?? `  guildDiscordId="123456789"`;
-      usage = `import { ${pascal} } from "@/components/calabasas/${firstInstalled.name}";
+        };
+        const props = propsMap[firstInstalled.name] ?? `  guildDiscordId="123456789"`;
+        usage = `import { ${pascal} } from "@/components/calabasas/${firstInstalled.name}";
 
 <${pascal}
 ${props}
 />`;
-    } else if (needsGuild) {
-      usage = `import { ${pascal} } from "@/components/calabasas/${firstInstalled.name}";
+      } else if (needsGuild) {
+        usage = `import { ${pascal} } from "@/components/calabasas/${firstInstalled.name}";
 
 <${pascal}
   guildDiscordId="123456789"
   onValueChange={(id) => console.log(id)}
 />`;
-    } else {
-      usage = `import { ${pascal} } from "@/components/calabasas/${firstInstalled.name}";
+      } else {
+        usage = `import { ${pascal} } from "@/components/calabasas/${firstInstalled.name}";
 
 <${pascal}
   onValueChange={(id) => console.log(id)}
 />`;
+      }
     }
     p7.note(usage, "Usage example");
   }
@@ -6354,7 +6516,7 @@ program2.command("logout").description("Clear stored credentials").option("--dev
 program2.command("init").description("Initialize Calabasas config in your Convex project").action(init);
 program2.command("push").description("Push your Calabasas config to the server").option("-c, --config <path>", "Path to config file", "convex/calabasas/config.ts").option("-b, --bot <botId>", "Bot ID to configure (prompts if not specified)").option("--dev", "Push to development environment").option("--prod", "Push to production environment").action(push);
 program2.command("generate").description("Generate type-safe Discord handlers and helpers").option("-o, --output <path>", "Output path", "convex/calabasas/_generated/discord.ts").action(generate);
-program2.command("skill").description("Generate Calabasas documentation for AI assistants").option("--dev", "Use development environment").option("--prod", "Use production environment").action(skill);
+program2.command("skill").description("Generate Calabasas documentation for AI assistants").option("--dev", "Use development environment").option("--prod", "Use production environment").option("-f, --file <path>", "Target file path (e.g. CLAUDE.md)").option("-y, --yes", "Auto-confirm replacing existing guidelines").action(skill);
 program2.command("add [components...]").description("Add Discord UI components to your project").action(add);
 program2.command("migrate [name]").description("Run a codemod migration (list available if no name given)").action(migrate);
 program2.command("status").alias("dashboard").description("Real-time dashboard showing bot status, events, and stats").option("--dev", "Use development environment").option("--prod", "Use production environment").action(dashboard);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "calabasas",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "CLI for Calabasas - Discord Gateway as a Service for Convex",
   "type": "module",
   "bin": {