optimal-cli 0.1.0 → 1.0.0

package/lib/auth/index.ts

@@ -0,0 +1,189 @@
+/**
+ * Auth module — ported from optimalOS Supabase auth patterns.
+ *
+ * OptimalOS uses three client tiers:
+ *   1. Browser client  (anon key + cookie session)  — N/A for CLI
+ *   2. Server client   (anon key + SSR cookies)      — N/A for CLI
+ *   3. Admin client    (service_role key, no session) — primary CLI path
+ *
+ * In a headless CLI context there are no cookies or browser sessions.
+ * Auth reduces to two modes:
+ *   - Service-role access  (bot / automation operations)
+ *   - User-scoped access   (pass an access_token obtained externally)
+ *
+ * Environment variables (defined in .env):
+ *   OPTIMAL_SUPABASE_URL          — Supabase project URL
+ *   OPTIMAL_SUPABASE_SERVICE_KEY  — service_role secret
+ */
+
+import { createClient, type SupabaseClient } from '@supabase/supabase-js'
+import 'dotenv/config'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Describes how the current invocation is authenticated. */
+export interface AuthContext {
+  /** 'service' when using service_role key, 'user' when using a user JWT */
+  mode: 'service' | 'user'
+  /** The Supabase client for this context */
+  client: SupabaseClient
+  /** User ID (only set when mode === 'user') */
+  userId?: string
+  /** User email (only set when mode === 'user' and resolvable) */
+  email?: string
+}
+
+/** Minimal session shape returned by getSession(). */
+export interface Session {
+  accessToken: string
+  user: {
+    id: string
+    email?: string
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function envOrThrow(name: string): string {
+  const value = process.env[name]
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`)
+  }
+  return value
+}
+
+/** Singleton service-role client (matches optimalOS admin.ts pattern). */
+let _serviceClient: SupabaseClient | null = null
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a service-role Supabase client.
+ *
+ * Mirrors optimalOS `createAdminClient()` from lib/supabase/admin.ts:
+ *   - Uses SUPABASE_SERVICE_ROLE_KEY
+ *   - persistSession: false, autoRefreshToken: false
+ *   - Singleton — safe to call repeatedly
+ */
+export function getServiceClient(): SupabaseClient {
+  if (_serviceClient) return _serviceClient
+
+  const url = envOrThrow('OPTIMAL_SUPABASE_URL')
+  const key = envOrThrow('OPTIMAL_SUPABASE_SERVICE_KEY')
+
+  _serviceClient = createClient(url, key, {
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+    },
+  })
+
+  return _serviceClient
+}
+
+/**
+ * Return a user-scoped Supabase client authenticated with the given JWT.
+ *
+ * This is the CLI equivalent of optimalOS browser/server clients that carry
+ * a user session via cookies. The caller is responsible for obtaining the
+ * access token (e.g., via `supabase login`, OAuth device flow, or env var).
+ *
+ * A new client is created on every call — callers should cache if needed.
+ */
+export function getUserClient(accessToken: string): SupabaseClient {
+  const url = envOrThrow('OPTIMAL_SUPABASE_URL')
+
+  // Use service key as the initial key — the global auth header override
+  // ensures all requests are scoped to the user's JWT instead.
+  const anonOrServiceKey = process.env.OPTIMAL_SUPABASE_ANON_KEY
+    ?? envOrThrow('OPTIMAL_SUPABASE_SERVICE_KEY')
+
+  return createClient(url, anonOrServiceKey, {
+    global: {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    },
+    auth: {
+      persistSession: false,
+      autoRefreshToken: false,
+    },
+  })
+}
+
+/**
+ * Attempt to retrieve the current session.
+ *
+ * In the CLI there is no implicit cookie jar. A session exists only when:
+ *   1. OPTIMAL_ACCESS_TOKEN env var is set (user JWT), or
+ *   2. A future `optimal login` command has cached a token locally.
+ *
+ * Returns null if no user session is available (service-role only mode).
+ */
+export async function getSession(): Promise<Session | null> {
+  const token = process.env.OPTIMAL_ACCESS_TOKEN
+  if (!token) return null
+
+  try {
+    const client = getUserClient(token)
+    const { data: { user }, error } = await client.auth.getUser(token)
+
+    if (error || !user) return null
+
+    return {
+      accessToken: token,
+      user: {
+        id: user.id,
+        email: user.email,
+      },
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Guard that throws if no user session is present.
+ *
+ * Use at the top of CLI commands that require a logged-in user:
+ *
+ *   const session = await requireAuth()
+ *   // session.user.id is guaranteed
+ */
+export async function requireAuth(): Promise<Session> {
+  const session = await getSession()
+  if (!session) {
+    throw new Error(
+      'Authentication required. Set OPTIMAL_ACCESS_TOKEN or run `optimal login`.',
+    )
+  }
+  return session
+}
+
+/**
+ * Build an AuthContext describing the current invocation's auth state.
+ *
+ * Prefers user-scoped auth when OPTIMAL_ACCESS_TOKEN is set;
+ * falls back to service-role.
+ */
+export async function resolveAuthContext(): Promise<AuthContext> {
+  const session = await getSession()
+
+  if (session) {
+    return {
+      mode: 'user',
+      client: getUserClient(session.accessToken),
+      userId: session.user.id,
+      email: session.user.email,
+    }
+  }
+
+  return {
+    mode: 'service',
+    client: getServiceClient(),
+  }
+}

package/lib/board/index.ts

@@ -0,0 +1,309 @@
+import { getSupabase } from '../supabase.js'
+import type {
+  Project, Task, Label, Comment, Milestone, ActivityEntry,
+  CreateProjectInput, CreateTaskInput, CreateCommentInput, CreateMilestoneInput,
+  UpdateTaskInput, TaskStatus,
+} from './types.js'
+
+export * from './types.js'
+
+const sb = () => getSupabase('optimal')
+
+// --- Helpers ---
+
+export function formatBoardTable(tasks: Task[]): string {
+  if (tasks.length === 0) return 'No tasks found.'
+  const lines = [
+    '| Status      | P | Title                          | Agent   | Skill           | Effort |',
+    '|-------------|---|--------------------------------|---------|-----------------|--------|',
+  ]
+  const order: TaskStatus[] = ['in_progress', 'claimed', 'blocked', 'ready', 'review', 'backlog', 'done']
+  const sorted = [...tasks].sort((a, b) => {
+    const ai = order.indexOf(a.status)
+    const bi = order.indexOf(b.status)
+    if (ai !== bi) return ai - bi
+    return a.priority - b.priority
+  })
+  for (const t of sorted) {
+    const title = t.title.length > 30 ? t.title.slice(0, 27) + '...' : t.title.padEnd(30)
+    const agent = (t.claimed_by ?? t.assigned_to ?? '—').padEnd(7)
+    const skill = (t.skill_required ?? '—').padEnd(15)
+    const effort = (t.estimated_effort ?? '—').padEnd(6)
+    lines.push(`| ${t.status.padEnd(11)} | ${t.priority} | ${title} | ${agent} | ${skill} | ${effort} |`)
+  }
+  lines.push(`\nTotal: ${tasks.length} tasks`)
+  return lines.join('\n')
+}
+
+export function getNextClaimable(readyTasks: Task[], allTasks: Task[]): Task | null {
+  for (const task of readyTasks) {
+    if (!task.blocked_by || task.blocked_by.length === 0) return task
+    const allDone = task.blocked_by.every(depId => {
+      const dep = allTasks.find(t => t.id === depId)
+      return dep && (dep.status === 'done')
+    })
+    if (allDone) return task
+  }
+  return null
+}
+
+// --- Projects ---
+
+export async function createProject(input: CreateProjectInput): Promise<Project> {
+  const { data, error } = await sb()
+    .from('projects')
+    .insert({
+      slug: input.slug,
+      name: input.name,
+      description: input.description ?? null,
+      owner: input.owner ?? null,
+      priority: input.priority ?? 3,
+    })
+    .select()
+    .single()
+  if (error) throw new Error(`Failed to create project: ${error.message}`)
+  return data as Project
+}
+
+export async function getProjectBySlug(slug: string): Promise<Project> {
+  const { data, error } = await sb()
+    .from('projects')
+    .select('*')
+    .eq('slug', slug)
+    .single()
+  if (error) throw new Error(`Project not found: ${slug} — ${error.message}`)
+  return data as Project
+}
+
+export async function listProjects(): Promise<Project[]> {
+  const { data, error } = await sb()
+    .from('projects')
+    .select('*')
+    .neq('status', 'archived')
+    .order('priority', { ascending: true })
+  if (error) throw new Error(`Failed to list projects: ${error.message}`)
+  return (data ?? []) as Project[]
+}
+
+export async function updateProject(slug: string, updates: Partial<Pick<Project, 'status' | 'owner' | 'priority' | 'description'>>): Promise<Project> {
+  const { data, error } = await sb()
+    .from('projects')
+    .update(updates)
+    .eq('slug', slug)
+    .select()
+    .single()
+  if (error) throw new Error(`Failed to update project: ${error.message}`)
+  return data as Project
+}
+
+// --- Milestones ---
+
+export async function createMilestone(input: CreateMilestoneInput): Promise<Milestone> {
+  const { data, error } = await sb()
+    .from('milestones')
+    .insert({
+      project_id: input.project_id,
+      name: input.name,
+      description: input.description ?? null,
+      due_date: input.due_date ?? null,
+    })
+    .select()
+    .single()
+  if (error) throw new Error(`Failed to create milestone: ${error.message}`)
+  return data as Milestone
+}
+
+export async function listMilestones(projectId?: string): Promise<Milestone[]> {
+  let query = sb().from('milestones').select('*').order('due_date', { ascending: true })
+  if (projectId) query = query.eq('project_id', projectId)
+  const { data, error } = await query
+  if (error) throw new Error(`Failed to list milestones: ${error.message}`)
+  return (data ?? []) as Milestone[]
+}
+
+// --- Labels ---
+
+export async function createLabel(name: string, color?: string): Promise<Label> {
+  const { data, error } = await sb()
+    .from('labels')
+    .insert({ name, color: color ?? null })
+    .select()
+    .single()
+  if (error) throw new Error(`Failed to create label: ${error.message}`)
+  return data as Label
+}
+
+export async function listLabels(): Promise<Label[]> {
+  const { data, error } = await sb().from('labels').select('*').order('name')
+  if (error) throw new Error(`Failed to list labels: ${error.message}`)
+  return (data ?? []) as Label[]
+}
+
+export async function getLabelByName(name: string): Promise<Label | null> {
+  const { data } = await sb().from('labels').select('*').eq('name', name).single()
+  return (data as Label) ?? null
+}
+
+// --- Tasks ---
+
+export async function createTask(input: CreateTaskInput): Promise<Task> {
+  const { labels: labelNames, ...rest } = input
+  const { data, error } = await sb()
+    .from('tasks')
+    .insert({
+      ...rest,
+      milestone_id: rest.milestone_id ?? null,
+      description: rest.description ?? null,
+      priority: rest.priority ?? 3,
+      skill_required: rest.skill_required ?? null,
+      source_repo: rest.source_repo ?? null,
+      target_module: rest.target_module ?? null,
+      estimated_effort: rest.estimated_effort ?? null,
+      blocked_by: rest.blocked_by ?? [],
+    })
+    .select()
+    .single()
+  if (error) throw new Error(`Failed to create task: ${error.message}`)
+  const task = data as Task
+
+  if (labelNames && labelNames.length > 0) {
+    for (const name of labelNames) {
+      const label = await getLabelByName(name)
+      if (label) {
+        await sb().from('task_labels').insert({ task_id: task.id, label_id: label.id })
+      }
+    }
+  }
+
+  await logActivity({ task_id: task.id, project_id: task.project_id, actor: 'system', action: 'created', new_value: { title: task.title } })
+  return task
+}
+
+export async function updateTask(taskId: string, updates: UpdateTaskInput, actor?: string): Promise<Task> {
+  const old = await getTask(taskId)
+  const { data, error } = await sb()
+    .from('tasks')
+    .update(updates)
+    .eq('id', taskId)
+    .select()
+    .single()
+  if (error) throw new Error(`Failed to update task ${taskId}: ${error.message}`)
+  const task = data as Task
+
+  if (actor) {
+    await logActivity({
+      task_id: taskId,
+      project_id: task.project_id,
+      actor,
+      action: updates.status ? 'status_changed' : 'updated',
+      old_value: { status: old.status, assigned_to: old.assigned_to },
+      new_value: updates as Record<string, unknown>,
+    })
+  }
+  return task
+}
+
+export async function getTask(taskId: string): Promise<Task> {
+  const { data, error } = await sb()
+    .from('tasks')
+    .select('*')
+    .eq('id', taskId)
+    .single()
+  if (error) throw new Error(`Task not found: ${taskId}`)
+  return data as Task
+}
+
+export async function listTasks(opts?: {
+  project_id?: string
+  status?: TaskStatus
+  claimed_by?: string
+  assigned_to?: string
+}): Promise<Task[]> {
+  let query = sb().from('tasks').select('*')
+  if (opts?.project_id) query = query.eq('project_id', opts.project_id)
+  if (opts?.status) query = query.eq('status', opts.status)
+  if (opts?.claimed_by) query = query.eq('claimed_by', opts.claimed_by)
+  if (opts?.assigned_to) query = query.eq('assigned_to', opts.assigned_to)
+  query = query.order('priority', { ascending: true }).order('sort_order', { ascending: true })
+  const { data, error } = await query
+  if (error) throw new Error(`Failed to list tasks: ${error.message}`)
+  return (data ?? []) as Task[]
+}
+
+export async function claimTask(taskId: string, agent: string): Promise<Task> {
+  const task = await updateTask(taskId, {
+    status: 'claimed',
+    claimed_by: agent,
+    claimed_at: new Date().toISOString(),
+  }, agent)
+
+  await addComment({ task_id: taskId, author: agent, body: `Claimed by ${agent}`, comment_type: 'claim' })
+  return task
+}
+
+export async function completeTask(taskId: string, actor: string): Promise<Task> {
+  return updateTask(taskId, {
+    status: 'done',
+    completed_at: new Date().toISOString(),
+  }, actor)
+}
+
+// --- Comments ---
+
+export async function addComment(input: CreateCommentInput): Promise<Comment> {
+  const { data, error } = await sb()
+    .from('comments')
+    .insert({
+      task_id: input.task_id,
+      author: input.author,
+      body: input.body,
+      comment_type: input.comment_type ?? 'comment',
+    })
+    .select()
+    .single()
+  if (error) throw new Error(`Failed to add comment: ${error.message}`)
+  return data as Comment
+}
+
+export async function listComments(taskId: string): Promise<Comment[]> {
+  const { data, error } = await sb()
+    .from('comments')
+    .select('*')
+    .eq('task_id', taskId)
+    .order('created_at', { ascending: true })
+  if (error) throw new Error(`Failed to list comments: ${error.message}`)
+  return (data ?? []) as Comment[]
+}
+
+// --- Activity Log ---
+
+export async function logActivity(entry: {
+  task_id?: string
+  project_id?: string
+  actor: string
+  action: string
+  old_value?: Record<string, unknown>
+  new_value?: Record<string, unknown>
+}): Promise<void> {
+  const { error } = await sb()
+    .from('activity_log')
+    .insert({
+      task_id: entry.task_id ?? null,
+      project_id: entry.project_id ?? null,
+      actor: entry.actor,
+      action: entry.action,
+      old_value: entry.old_value ?? null,
+      new_value: entry.new_value ?? null,
+    })
+  if (error) throw new Error(`Failed to log activity: ${error.message}`)
+}
+
+export async function listActivity(opts?: { task_id?: string; actor?: string; limit?: number }): Promise<ActivityEntry[]> {
+  let query = sb().from('activity_log').select('*')
+  if (opts?.task_id) query = query.eq('task_id', opts.task_id)
+  if (opts?.actor) query = query.eq('actor', opts.actor)
+  query = query.order('created_at', { ascending: false }).limit(opts?.limit ?? 50)
+  const { data, error } = await query
+  if (error) throw new Error(`Failed to list activity: ${error.message}`)
+  return (data ?? []) as ActivityEntry[]
+}

package/lib/board/types.ts

@@ -0,0 +1,124 @@
+export interface Project {
+  id: string
+  slug: string
+  name: string
+  description: string | null
+  status: 'active' | 'paused' | 'completed' | 'archived'
+  owner: string | null
+  priority: 1 | 2 | 3 | 4
+  created_at: string
+  updated_at: string
+}
+
+export interface Milestone {
+  id: string
+  project_id: string
+  name: string
+  description: string | null
+  due_date: string | null
+  status: 'open' | 'completed' | 'missed'
+  created_at: string
+  updated_at: string
+}
+
+export interface Label {
+  id: string
+  name: string
+  color: string | null
+  created_at: string
+}
+
+export type TaskStatus = 'backlog' | 'ready' | 'claimed' | 'in_progress' | 'review' | 'done' | 'blocked'
+export type Priority = 1 | 2 | 3 | 4
+export type Effort = 'xs' | 's' | 'm' | 'l' | 'xl'
+
+export interface Task {
+  id: string
+  project_id: string
+  milestone_id: string | null
+  title: string
+  description: string | null
+  status: TaskStatus
+  priority: Priority
+  assigned_to: string | null
+  claimed_by: string | null
+  claimed_at: string | null
+  skill_required: string | null
+  source_repo: string | null
+  target_module: string | null
+  estimated_effort: Effort | null
+  blocked_by: string[]
+  sort_order: number
+  created_at: string
+  updated_at: string
+  completed_at: string | null
+}
+
+export interface Comment {
+  id: string
+  task_id: string
+  author: string
+  body: string
+  comment_type: 'comment' | 'status_change' | 'claim' | 'review'
+  created_at: string
+}
+
+export interface ActivityEntry {
+  id: string
+  task_id: string | null
+  project_id: string | null
+  actor: string
+  action: string
+  old_value: Record<string, unknown> | null
+  new_value: Record<string, unknown> | null
+  created_at: string
+}
+
+// --- Input types ---
+
+export interface CreateProjectInput {
+  slug: string
+  name: string
+  description?: string
+  owner?: string
+  priority?: Priority
+}
+
+export interface CreateMilestoneInput {
+  project_id: string
+  name: string
+  description?: string
+  due_date?: string
+}
+
+export interface CreateTaskInput {
+  project_id: string
+  title: string
+  description?: string
+  priority?: Priority
+  milestone_id?: string
+  skill_required?: string
+  source_repo?: string
+  target_module?: string
+  estimated_effort?: Effort
+  blocked_by?: string[]
+  labels?: string[]
+}
+
+export interface UpdateTaskInput {
+  status?: TaskStatus
+  priority?: Priority
+  assigned_to?: string | null
+  claimed_by?: string | null
+  claimed_at?: string | null
+  milestone_id?: string | null
+  description?: string
+  completed_at?: string | null
+}
+
+export interface CreateCommentInput {
+  task_id: string
+  author: string
+  body: string
+  comment_type?: 'comment' | 'status_change' | 'claim' | 'review'
+}

package/lib/bot/claim.ts

@@ -0,0 +1,43 @@
+import {
+  listTasks,
+  claimTask,
+  updateTask,
+  getNextClaimable,
+  type Task,
+} from '../board/index.js'
+
+export async function claimNextTask(
+  agentId: string,
+  skills?: string[],
+): Promise<Task | null> {
+  const readyTasks = await listTasks({ status: 'ready' })
+  const allTasks = await listTasks()
+
+  let candidates = readyTasks
+  if (skills && skills.length > 0) {
+    candidates = readyTasks.filter(
+      (t) => !t.skill_required || skills.includes(t.skill_required),
+    )
+  }
+
+  const next = getNextClaimable(candidates, allTasks)
+  if (!next) return null
+
+  return claimTask(next.id, agentId)
+}
+
+export async function releaseTask(
+  taskId: string,
+  agentId: string,
+  reason?: string,
+): Promise<Task> {
+  return updateTask(
+    taskId,
+    {
+      status: 'ready',
+      claimed_by: null,
+      claimed_at: null,
+    },
+    agentId,
+  )
+}