@lakitu/sdk 0.1.0

package/convex/sandbox/planning/beads.ts

@@ -0,0 +1,187 @@
+/**
+ * Beads - Task Tracking
+ *
+ * CRUD operations for task tracking with CRDT support
+ */
+
+import { mutation, query } from "../_generated/server";
+import { v } from "convex/values";
+
+// ============================================
+// Mutations
+// ============================================
+
+export const create = mutation({
+  args: {
+    title: v.string(),
+    type: v.union(
+      v.literal("task"),
+      v.literal("bug"),
+      v.literal("feature"),
+      v.literal("chore"),
+      v.literal("epic")
+    ),
+    priority: v.optional(v.number()),
+    description: v.optional(v.string()),
+    labels: v.optional(v.array(v.string())),
+    parentId: v.optional(v.id("beads")),
+    threadId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("beads", {
+      title: args.title,
+      type: args.type,
+      status: "open",
+      priority: args.priority ?? 2,
+      description: args.description,
+      labels: args.labels,
+      parentId: args.parentId,
+      threadId: args.threadId,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+export const update = mutation({
+  args: {
+    id: v.id("beads"),
+    status: v.optional(
+      v.union(
+        v.literal("open"),
+        v.literal("in_progress"),
+        v.literal("blocked"),
+        v.literal("closed")
+      )
+    ),
+    priority: v.optional(v.number()),
+    title: v.optional(v.string()),
+    description: v.optional(v.string()),
+    labels: v.optional(v.array(v.string())),
+    blockedBy: v.optional(v.array(v.id("beads"))),
+  },
+  handler: async (ctx, args) => {
+    const { id, ...updates } = args;
+    const filtered = Object.fromEntries(
+      Object.entries(updates).filter(([_, v]) => v !== undefined)
+    );
+
+    await ctx.db.patch(id, {
+      ...filtered,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+export const close = mutation({
+  args: {
+    id: v.id("beads"),
+    reason: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.id, {
+      status: "closed",
+      closedAt: Date.now(),
+      closeReason: args.reason,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+// ============================================
+// Queries
+// ============================================
+
+export const get = query({
+  args: { id: v.id("beads") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.id);
+  },
+});
+
+export const list = query({
+  args: {
+    status: v.optional(
+      v.union(
+        v.literal("open"),
+        v.literal("in_progress"),
+        v.literal("blocked"),
+        v.literal("closed")
+      )
+    ),
+    type: v.optional(
+      v.union(
+        v.literal("task"),
+        v.literal("bug"),
+        v.literal("feature"),
+        v.literal("chore"),
+        v.literal("epic")
+      )
+    ),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { status, type } = args;
+    const limit = args.limit ?? 50;
+
+    // Use index if status is specified, otherwise full table scan
+    const items = status
+      ? await ctx.db
+          .query("beads")
+          .withIndex("by_status", (q) => q.eq("status", status))
+          .order("desc")
+          .take(limit)
+      : await ctx.db.query("beads").order("desc").take(limit);
+
+    // Filter by type if specified (after index query)
+    if (type) {
+      return items.filter((i) => i.type === type);
+    }
+
+    return items;
+  },
+});
+
+export const getReady = query({
+  args: { limit: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    // Get all open tasks
+    const open = await ctx.db
+      .query("beads")
+      .withIndex("by_status", (q) => q.eq("status", "open"))
+      .collect();
+
+    // Filter out blocked tasks (those with unresolved blockedBy)
+    const ready = [];
+    for (const task of open) {
+      if (task.blockedBy && task.blockedBy.length > 0) {
+        // Check if all blockers are resolved
+        const blockers = await Promise.all(
+          task.blockedBy.map((id) => ctx.db.get(id))
+        );
+        const unresolvedBlockers = blockers.filter(
+          (b) => b && b.status !== "closed"
+        );
+        if (unresolvedBlockers.length > 0) {
+          continue; // Still blocked
+        }
+      }
+      ready.push(task);
+    }
+
+    // Sort by priority (ascending = higher priority first)
+    ready.sort((a, b) => a.priority - b.priority);
+
+    return ready.slice(0, args.limit ?? 10);
+  },
+});
+
+export const getByThread = query({
+  args: { threadId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("beads")
+      .withIndex("by_thread", (q) => q.eq("threadId", args.threadId))
+      .collect();
+  },
+});

package/convex/sandbox/planning/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Planning - Task Planning & Coordination
+ *
+ * Beads-style issue tracking with dependency resolution.
+ */
+
+export * as beads from "./beads";
+export * as sync from "./sync";

package/convex/sandbox/planning/sync.ts

@@ -0,0 +1,194 @@
+/**
+ * Sync - Cloud ↔ Sandbox Synchronization
+ *
+ * Queue items for sync to cloud Convex.
+ * Handle artifact uploads, state snapshots, and result reporting.
+ */
+
+import { mutation, query, internalMutation } from "../_generated/server";
+import { v } from "convex/values";
+
+// ============================================
+// Mutations
+// ============================================
+
+/**
+ * Queue an item for sync to cloud
+ */
+export const queueSync = mutation({
+  args: {
+    type: v.union(
+      v.literal("artifact"),
+      v.literal("bead"),
+      v.literal("decision"),
+      v.literal("checkpoint"),
+      v.literal("result")
+    ),
+    itemId: v.string(),
+    priority: v.optional(v.number()), // 0 = highest
+    metadata: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("syncQueue", {
+      type: args.type,
+      itemId: args.itemId,
+      status: "pending",
+      priority: args.priority ?? 5,
+      metadata: args.metadata,
+      createdAt: Date.now(),
+      attempts: 0,
+    });
+  },
+});
+
+/**
+ * Mark sync item as in progress
+ */
+export const markInProgress = internalMutation({
+  args: { id: v.id("syncQueue") },
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.id, {
+      status: "in_progress",
+      startedAt: Date.now(),
+    });
+  },
+});
+
+/**
+ * Mark sync item as completed
+ */
+export const markCompleted = internalMutation({
+  args: {
+    id: v.id("syncQueue"),
+    cloudId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.id, {
+      status: "completed",
+      completedAt: Date.now(),
+      cloudId: args.cloudId,
+    });
+  },
+});
+
+/**
+ * Mark sync item as failed
+ */
+export const markFailed = internalMutation({
+  args: {
+    id: v.id("syncQueue"),
+    error: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const item = await ctx.db.get(args.id);
+    if (!item) return;
+
+    await ctx.db.patch(args.id, {
+      status: item.attempts >= 3 ? "failed" : "pending",
+      lastError: args.error,
+      lastAttemptAt: Date.now(),
+      attempts: item.attempts + 1,
+    });
+  },
+});
+
+/**
+ * Clear completed sync items
+ */
+export const clearCompleted = mutation({
+  args: { olderThanMs: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    const cutoff = Date.now() - (args.olderThanMs ?? 3600000); // 1 hour default
+
+    const completed = await ctx.db
+      .query("syncQueue")
+      .withIndex("by_status", (q) => q.eq("status", "completed"))
+      .collect();
+
+    let deleted = 0;
+    for (const item of completed) {
+      if (item.completedAt && item.completedAt < cutoff) {
+        await ctx.db.delete(item._id);
+        deleted++;
+      }
+    }
+
+    return { deleted };
+  },
+});
+
+// ============================================
+// Queries
+// ============================================
+
+/**
+ * Get pending sync items
+ */
+export const getPending = query({
+  args: { limit: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    const items = await ctx.db
+      .query("syncQueue")
+      .withIndex("by_status", (q) => q.eq("status", "pending"))
+      .take(args.limit ?? 50);
+
+    // Sort by priority (ascending)
+    return items.sort((a, b) => a.priority - b.priority);
+  },
+});
+
+/**
+ * Get sync queue status
+ */
+export const getStatus = query({
+  args: {},
+  handler: async (ctx) => {
+    const pending = await ctx.db
+      .query("syncQueue")
+      .withIndex("by_status", (q) => q.eq("status", "pending"))
+      .collect();
+
+    const inProgress = await ctx.db
+      .query("syncQueue")
+      .withIndex("by_status", (q) => q.eq("status", "in_progress"))
+      .collect();
+
+    const failed = await ctx.db
+      .query("syncQueue")
+      .withIndex("by_status", (q) => q.eq("status", "failed"))
+      .collect();
+
+    return {
+      pending: pending.length,
+      inProgress: inProgress.length,
+      failed: failed.length,
+      oldestPending: pending[0]?.createdAt,
+    };
+  },
+});
+
+/**
+ * Get failed sync items for retry
+ */
+export const getFailed = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db
+      .query("syncQueue")
+      .withIndex("by_status", (q) => q.eq("status", "failed"))
+      .collect();
+  },
+});
+
+/**
+ * Get sync history for an item
+ */
+export const getByItemId = query({
+  args: { itemId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("syncQueue")
+      .filter((q) => q.eq(q.field("itemId"), args.itemId))
+      .collect();
+  },
+});