claude-code-swarm 0.3.2 → 0.3.4

package/references/opentasks/src/client/__tests__/socket-discovery.test.ts

@@ -1,122 +0,0 @@
-/**
- * Tests for client socket discovery and global auto-init
- *
- * Verifies the 3-tier fallback (git → project → global) and
- * that ~/.opentasks/ is auto-initialized when no other socket is found.
- */
-
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import * as fs from 'node:fs';
-import * as fsp from 'node:fs/promises';
-import * as path from 'node:path';
-import * as os from 'node:os';
-
-// Mock ensureGlobalStoreInitialized before importing client
-const mockEnsureGlobalStoreInitialized = vi.fn();
-
-vi.mock('../../core/init.js', () => ({
-  ensureGlobalStoreInitialized: (...args: unknown[]) => mockEnsureGlobalStoreInitialized(...args),
-}));
-
-// Mock worktree module to control git detection
-vi.mock('../../core/worktree.js', () => ({
-  getGitCommonDir: vi.fn(() => null),
-}));
-
-import { OpenTasksClient, ClientError } from '../client.js';
-
-describe('socket discovery with auto-init', () => {
-  let tmpDir: string;
-  let originalCwd: typeof process.cwd;
-
-  beforeEach(async () => {
-    vi.clearAllMocks();
-    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'opentasks-discovery-test-'));
-    originalCwd = process.cwd;
-
-    // Default: cwd is in a subdirectory with no .opentasks/ in its walk-up path
-    // Use a nested dir so findOpenTasksDir() doesn't find anything
-    const nestedDir = path.join(tmpDir, 'some', 'deep', 'path');
-    await fsp.mkdir(nestedDir, { recursive: true });
-    process.cwd = () => nestedDir;
-
-    // Default: ensureGlobalStoreInitialized returns a path (but no daemon.sock there)
-    const globalDir = path.join(tmpDir, 'fakehome', '.opentasks');
-    await fsp.mkdir(globalDir, { recursive: true });
-    mockEnsureGlobalStoreInitialized.mockReturnValue(globalDir);
-  });
-
-  afterEach(async () => {
-    process.cwd = originalCwd;
-    await fsp.rm(tmpDir, { recursive: true, force: true });
-  });
-
-  it('calls ensureGlobalStoreInitialized when no git or project socket found', async () => {
-    const client = new OpenTasksClient({ autoConnect: false });
-
-    // connect() resolves socket via getDefaultSocketPath()
-    // No git socket, no project .opentasks/, so falls through to global
-    // ensureGlobalStoreInitialized is called but no daemon.sock exists → SOCKET_NOT_FOUND
-    await expect(client.connect()).rejects.toMatchObject({
-      code: 'SOCKET_NOT_FOUND',
-    });
-
-    expect(mockEnsureGlobalStoreInitialized).toHaveBeenCalledTimes(1);
-  });
-
-  it('throws SOCKET_NOT_FOUND when global dir is initialized but daemon is not running', async () => {
-    const globalDir = path.join(tmpDir, 'fakehome', '.opentasks');
-    // Directory exists (from beforeEach) but no daemon.sock
-    mockEnsureGlobalStoreInitialized.mockReturnValue(globalDir);
-
-    const client = new OpenTasksClient({ autoConnect: false });
-
-    await expect(client.connect()).rejects.toMatchObject({
-      code: 'SOCKET_NOT_FOUND',
-    });
-  });
-
-  it('attempts connection when global daemon.sock exists', async () => {
-    const globalDir = path.join(tmpDir, 'fakehome', '.opentasks');
-    // Create a fake daemon.sock file so discovery succeeds
-    await fsp.writeFile(path.join(globalDir, 'daemon.sock'), '');
-    mockEnsureGlobalStoreInitialized.mockReturnValue(globalDir);
-
-    const client = new OpenTasksClient({ autoConnect: false });
-
-    // Gets past SOCKET_NOT_FOUND (socket file exists) but actual IPC connection fails
-    await expect(client.connect()).rejects.toMatchObject({
-      code: 'CONNECTION_FAILED',
-    });
-
-    expect(mockEnsureGlobalStoreInitialized).toHaveBeenCalledTimes(1);
-  });
-
-  it('prefers project .opentasks/ socket over global', async () => {
-    // Create project-level .opentasks/ with a fake daemon.sock in the cwd walk-up path
-    const projectDir = path.join(tmpDir, 'some', '.opentasks');
-    await fsp.mkdir(projectDir, { recursive: true });
-    await fsp.writeFile(path.join(projectDir, 'daemon.sock'), '');
-
-    const client = new OpenTasksClient({ autoConnect: false });
-
-    // Should find project socket first and skip global fallback
-    await expect(client.connect()).rejects.toMatchObject({
-      code: 'CONNECTION_FAILED',
-    });
-
-    expect(mockEnsureGlobalStoreInitialized).not.toHaveBeenCalled();
-  });
-
-  it('does not call ensureGlobalStoreInitialized when socketPath is explicitly provided', async () => {
-    const client = new OpenTasksClient({
-      socketPath: '/nonexistent/daemon.sock',
-      autoConnect: false,
-    });
-
-    await expect(client.connect()).rejects.toThrow(ClientError);
-
-    // Socket path was explicit — no discovery, no auto-init
-    expect(mockEnsureGlobalStoreInitialized).not.toHaveBeenCalled();
-  });
-});

package/references/opentasks/src/client/client.ts

@@ -1,560 +0,0 @@
-/**
- * OpenTasks Client
- *
- * Client library for interacting with the OpenTasks daemon.
- * Provides a typed wrapper around the 3-tool interface.
- */
-
-import * as path from 'node:path';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import { createIPCClient, type IPCClient } from '../daemon/ipc.js';
-import { getGitCommonDir } from '../core/worktree.js';
-import { ensureGlobalStoreInitialized } from '../core/init.js';
-import type {
-  LinkParams,
-  LinkResult,
-  QueryParams,
-  QueryResult,
-  AnnotateParams,
-  AnnotateResult,
-  TaskParams,
-  TaskResult,
-  NodeSummary,
-  FeedbackSummary,
-  ReadyOptions,
-  BlockerOptions,
-  FeedbackOptions,
-} from '../tools/types.js';
-import type { CreateNodeInput, UpdateNodeInput, DeleteOptions } from '../graph/types.js';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Options for creating an OpenTasks client
- */
-export interface ClientOptions {
-  /** Path to the daemon socket file */
-  socketPath?: string;
-
-  /** Auto-connect on first request (default: true) */
-  autoConnect?: boolean;
-
-  /** Request timeout in milliseconds (default: 30000) */
-  timeout?: number;
-}
-
-/**
- * Error thrown when client operations fail
- */
-export class ClientError extends Error {
-  constructor(
-    message: string,
-    public readonly code:
-      | 'NOT_CONNECTED'
-      | 'CONNECTION_FAILED'
-      | 'REQUEST_FAILED'
-      | 'SOCKET_NOT_FOUND',
-  ) {
-    super(message);
-    this.name = 'ClientError';
-  }
-}
-
-// ============================================================================
-// Socket Path Discovery
-// ============================================================================
-
-/**
- * Find the multi-location daemon socket at .git/opentasks/daemon.sock
- */
-function findGitDaemonSocket(startDir: string = process.cwd()): string | null {
-  const gitCommonDir = getGitCommonDir(startDir);
-  if (!gitCommonDir) return null;
-
-  const socketPath = path.join(gitCommonDir, 'opentasks', 'daemon.sock');
-  if (fs.existsSync(socketPath)) {
-    return socketPath;
-  }
-  return null;
-}
-
-/**
- * Find the opentasks directory starting from cwd and walking up.
- * Priority: OPENTASKS_PROJECT_DIR env var > .swarm/opentasks > .opentasks
- */
-function findOpenTasksDir(startDir: string = process.cwd()): string | null {
-  // Explicit override via env var
-  if (process.env.OPENTASKS_PROJECT_DIR) {
-    const explicit = path.resolve(startDir, process.env.OPENTASKS_PROJECT_DIR);
-    if (fs.existsSync(explicit) && fs.statSync(explicit).isDirectory()) {
-      return explicit;
-    }
-  }
-
-  let currentDir = startDir;
-
-  while (true) {
-    // Check swarmkit-managed layout first, then standalone
-    const swarmCandidate = path.join(currentDir, '.swarm', 'opentasks');
-    if (fs.existsSync(swarmCandidate) && fs.statSync(swarmCandidate).isDirectory()) {
-      return swarmCandidate;
-    }
-
-    const candidate = path.join(currentDir, '.opentasks');
-    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
-      return candidate;
-    }
-
-    const parentDir = path.dirname(currentDir);
-    if (parentDir === currentDir) {
-      // Reached root
-      return null;
-    }
-    currentDir = parentDir;
-  }
-}
-
-/**
- * Get the default socket path.
- * Prefers .git/opentasks/daemon.sock (multi-location), then walks up for
- * .opentasks/daemon.sock (single-location), then falls back to
- * ~/.opentasks/daemon.sock (global store).
- */
-function getDefaultSocketPath(): string {
-  // 1. Check for multi-location daemon socket first
-  const gitSocket = findGitDaemonSocket();
-  if (gitSocket) {
-    return gitSocket;
-  }
-
-  // 2. Fallback to single-location .opentasks/daemon.sock
-  const openTasksDir = findOpenTasksDir();
-  if (openTasksDir) {
-    return path.join(openTasksDir, 'daemon.sock');
-  }
-
-  // 3. Fallback to global daemon at ~/.opentasks/daemon.sock
-  // Auto-init ~/.opentasks/ if it doesn't exist yet
-  const globalDir = ensureGlobalStoreInitialized();
-  const globalSocketPath = path.join(globalDir, 'daemon.sock');
-  if (fs.existsSync(globalSocketPath)) {
-    return globalSocketPath;
-  }
-
-  throw new ClientError(
-    'Could not find daemon socket. Is the daemon running?',
-    'SOCKET_NOT_FOUND',
-  );
-}
-
-// ============================================================================
-// Client Implementation
-// ============================================================================
-
-/**
- * Client for interacting with the OpenTasks daemon
- *
- * Provides typed access to the 3-tool interface (link, query, annotate)
- * plus convenience methods for common operations.
- *
- * @example
- * ```typescript
- * const client = new OpenTasksClient()
- *
- * // Find ready work
- * const ready = await client.ready()
- *
- * // Create a relationship
- * await client.link({
- *   from_id: 'i-abc1',
- *   to_id: 's-def2',
- *   type: 'implements'
- * })
- *
- * // Add feedback
- * await client.annotate({
- *   target_id: 's-def2',
- *   create: { content: 'Implementation complete' }
- * })
- *
- * client.disconnect()
- * ```
- */
-export class OpenTasksClient {
-  private client: IPCClient | null = null;
-  private readonly options: Required<ClientOptions>;
-  private socketPath: string | null = null;
-
-  constructor(options?: ClientOptions) {
-    this.options = {
-      socketPath: options?.socketPath ?? '',
-      autoConnect: options?.autoConnect ?? true,
-      timeout: options?.timeout ?? 30000,
-    };
-
-    // If socket path provided, resolve it immediately
-    if (options?.socketPath) {
-      this.socketPath = options.socketPath;
-    }
-  }
-
-  // ==========================================================================
-  // Connection Lifecycle
-  // ==========================================================================
-
-  /**
-   * Connect to the daemon
-   */
-  async connect(): Promise<void> {
-    if (this.client?.connected) {
-      return;
-    }
-
-    // Resolve socket path if not already done
-    if (!this.socketPath) {
-      this.socketPath = getDefaultSocketPath();
-    }
-
-    this.client = createIPCClient(this.socketPath);
-
-    try {
-      await this.client.connect();
-    } catch (error) {
-      this.client = null;
-      throw new ClientError(
-        `Failed to connect to daemon: ${error instanceof Error ? error.message : 'Unknown error'}`,
-        'CONNECTION_FAILED',
-      );
-    }
-  }
-
-  /**
-   * Disconnect from the daemon
-   */
-  disconnect(): void {
-    if (this.client) {
-      this.client.disconnect();
-      this.client = null;
-    }
-  }
-
-  /**
-   * Check if connected to the daemon
-   */
-  get connected(): boolean {
-    return this.client?.connected ?? false;
-  }
-
-  /**
-   * Ensure connection before making a request
-   */
-  private async ensureConnected(): Promise<void> {
-    if (this.connected) {
-      return;
-    }
-
-    if (this.options.autoConnect) {
-      await this.connect();
-      return;
-    }
-
-    throw new ClientError(
-      'Not connected to daemon. Call connect() first or enable autoConnect.',
-      'NOT_CONNECTED',
-    );
-  }
-
-  // ==========================================================================
-  // Core Tools
-  // ==========================================================================
-
-  /**
-   * Create or remove an edge between nodes
-   *
-   * @param params - Link parameters
-   * @returns Link result with success status
-   */
-  async link(params: LinkParams): Promise<LinkResult> {
-    await this.ensureConnected();
-    return this.client!.request<LinkResult>('tools.link', params);
-  }
-
-  /**
-   * Query the graph
-   *
-   * @param params - Query parameters
-   * @returns Query result with items and pagination info
-   */
-  async query(params: QueryParams): Promise<QueryResult> {
-    await this.ensureConnected();
-    return this.client!.request<QueryResult>('tools.query', params);
-  }
-
-  /**
-   * Manage feedback lifecycle
-   *
-   * @param params - Annotate parameters
-   * @returns Annotate result with success status
-   */
-  async annotate(params: AnnotateParams): Promise<AnnotateResult> {
-    await this.ensureConnected();
-    return this.client!.request<AnnotateResult>('tools.annotate', params);
-  }
-
-  /**
-   * Task lifecycle operations
-   *
-   * @param params - Task parameters (transition, ready, assign, or validActions)
-   * @returns Task result with operation-specific data
-   */
-  async task(params: TaskParams): Promise<TaskResult> {
-    await this.ensureConnected();
-    return this.client!.request<TaskResult>('tools.task', params);
-  }
-
-  // ==========================================================================
-  // Convenience Methods
-  // ==========================================================================
-
-  /**
-   * Get issues ready to work on (no active blockers)
-   *
-   * @param options - Ready query options
-   * @returns Array of ready issue summaries
-   */
-  async ready(options?: ReadyOptions): Promise<NodeSummary[]> {
-    const result = await this.query({ ready: options || {} });
-    return result.items as NodeSummary[];
-  }
-
-  /**
-   * Get nodes blocking a specific node
-   *
-   * @param nodeId - Node to find blockers for
-   * @param options - Blocker query options
-   * @returns Array of blocking node summaries
-   */
-  async blockers(nodeId: string, options?: Omit<BlockerOptions, 'nodeId'>): Promise<NodeSummary[]> {
-    const result = await this.query({
-      blockers: { nodeId, ...options },
-    });
-    return result.items as NodeSummary[];
-  }
-
-  /**
-   * Get nodes blocked by a specific node
-   *
-   * @param nodeId - Node to find blocked nodes for
-   * @param options - Blocker query options
-   * @returns Array of blocked node summaries
-   */
-  async blocking(nodeId: string, options?: Omit<BlockerOptions, 'nodeId'>): Promise<NodeSummary[]> {
-    const result = await this.query({
-      blocking: { nodeId, ...options },
-    });
-    return result.items as NodeSummary[];
-  }
-
-  /**
-   * Get feedback on a specific node
-   *
-   * @param nodeId - Node to get feedback for
-   * @param options - Feedback query options
-   * @returns Array of feedback summaries
-   */
-  async feedback(
-    nodeId: string,
-    options?: Omit<FeedbackOptions, 'nodeId'>,
-  ): Promise<FeedbackSummary[]> {
-    const result = await this.query({
-      feedback: { nodeId, ...options },
-    });
-    return result.items as FeedbackSummary[];
-  }
-
-  /**
-   * Transition a task's status using a semantic action
-   *
-   * @param id - Task ID or provider URI
-   * @param action - Semantic action ('start', 'complete', 'block', 'reopen', 'close')
-   * @returns Task result with updated node
-   */
-  async taskTransition(
-    id: string,
-    action: 'start' | 'complete' | 'block' | 'reopen' | 'close',
-  ): Promise<TaskResult> {
-    return this.task({ transition: { id, action } });
-  }
-
-  /**
-   * Get tasks ready to work on across all task-capable providers
-   *
-   * @param options - Ready task query options
-   * @returns Task result with ready items
-   */
-  async taskReady(options?: {
-    providers?: string[];
-    limit?: number;
-    tags?: string[];
-  }): Promise<TaskResult> {
-    return this.task({ ready: options || {} });
-  }
-
-  /**
-   * Assign a task to an owner
-   *
-   * @param id - Task ID or provider URI
-   * @param assignee - Assignee identifier
-   * @returns Task result with updated node
-   */
-  async taskAssign(id: string, assignee: string): Promise<TaskResult> {
-    return this.task({ assign: { id, assignee } });
-  }
-
-  /**
-   * Get valid next actions for a task in its current state
-   *
-   * @param id - Task ID or provider URI
-   * @returns Task result with valid actions
-   */
-  async taskValidActions(id: string): Promise<TaskResult> {
-    return this.task({ validActions: { id } });
-  }
-
-  // ==========================================================================
-  // Graph CRUD (with unified provider dispatch)
-  // ==========================================================================
-
-  /**
-   * Create a node.
-   * When `scheme` is provided, routes creation to that provider.
-   * Otherwise uses the configured defaultProvider.
-   *
-   * @param params - Node creation parameters
-   * @param options - Optional provider routing options
-   * @returns The created node (materialized locally if via external provider)
-   */
-  async createNode(params: CreateNodeInput, options?: { scheme?: string }): Promise<unknown> {
-    await this.ensureConnected();
-    return this.client!.request('graph.create', { ...params, scheme: options?.scheme });
-  }
-
-  /**
-   * Get a node by local ID or provider URI.
-   * For external/materialized nodes, refreshes if stale.
-   *
-   * @param idOrUri - Local node ID (e.g., 'i-abc1') or provider URI (e.g., 'sudocode://proj/i-456')
-   */
-  async getNode(idOrUri: string): Promise<unknown> {
-    await this.ensureConnected();
-    return this.client!.request('graph.get', { id: idOrUri });
-  }
-
-  /**
-   * Update a node by local ID or provider URI.
-   * For external/materialized nodes, routes update to the owning provider.
-   *
-   * @param idOrUri - Local node ID or provider URI
-   * @param updates - Fields to update
-   */
-  async updateNode(idOrUri: string, updates: UpdateNodeInput): Promise<unknown> {
-    await this.ensureConnected();
-    return this.client!.request('graph.update', { id: idOrUri, ...updates });
-  }
-
-  /**
-   * Delete a node by local ID or provider URI.
-   * For external/materialized nodes, deletes in the owning provider
-   * and removes the local materialized copy.
-   *
-   * @param idOrUri - Local node ID or provider URI
-   * @param options - Delete options (hard vs soft)
-   */
-  async deleteNode(idOrUri: string, options?: DeleteOptions): Promise<void> {
-    await this.ensureConnected();
-    await this.client!.request('graph.delete', { id: idOrUri, options });
-  }
-
-  // ==========================================================================
-  // Provider Introspection
-  // ==========================================================================
-
-  /**
-   * List all registered providers and their capabilities
-   */
-  async listProviders(): Promise<unknown> {
-    await this.ensureConnected();
-    return this.client!.request('provider.list', {});
-  }
-
-  /**
-   * Get info about a specific provider
-   *
-   * @param name - Provider name
-   */
-  async getProvider(name: string): Promise<unknown> {
-    await this.ensureConnected();
-    return this.client!.request('provider.info', { name });
-  }
-
-  // ==========================================================================
-  // Skill Tracking
-  // ==========================================================================
-
-  /**
-   * Get skill usage summary for a specific session/trajectory
-   *
-   * @param sessionId - Session ID to query
-   * @returns Skill usage summary or null if session not found
-   */
-  async skillUsage(sessionId: string): Promise<unknown> {
-    await this.ensureConnected();
-    return this.client!.request('tracking.skills', { sessionId });
-  }
-
-  /**
-   * Get skill usage summaries for all active sessions
-   *
-   * @returns Array of skill usage summaries
-   */
-  async allSkillUsage(): Promise<unknown> {
-    await this.ensureConnected();
-    return this.client!.request('tracking.skills.all', {});
-  }
-
-  /**
-   * End skill tracking for a session and return the final summary
-   *
-   * @param sessionId - Session ID to finalize
-   * @returns Final skill usage summary or null if session not found
-   */
-  async endSkillTracking(sessionId: string): Promise<unknown> {
-    await this.ensureConnected();
-    return this.client!.request('tracking.skills.end', { sessionId });
-  }
-
-  // ==========================================================================
-  // Generic RPC
-  // ==========================================================================
-
-  /**
-   * Call any daemon method by name
-   */
-  async call<R = unknown>(method: string, params?: unknown): Promise<R> {
-    await this.ensureConnected();
-    return this.client!.request<R>(method, params);
-  }
-}
-
-/**
- * Create a new OpenTasks client
- *
- * @param options - Client options
- * @returns OpenTasks client instance
- */
-export function createClient(options?: ClientOptions): OpenTasksClient {
-  return new OpenTasksClient(options);
-}

package/references/opentasks/src/client/index.ts

@@ -1,32 +0,0 @@
-/**
- * OpenTasks Client Module
- *
- * Client library for interacting with the OpenTasks daemon.
- *
- * @packageDocumentation
- */
-
-// Client
-export type { ClientOptions } from './client.js';
-export { OpenTasksClient, ClientError, createClient } from './client.js';
-
-// Re-export tool types for convenience
-export type {
-  LinkParams,
-  LinkResult,
-  QueryParams,
-  QueryResult,
-  AnnotateParams,
-  AnnotateResult,
-  NodeSummary,
-  EdgeSummary,
-  FeedbackSummary,
-  BlockerQueryParams,
-  FeedbackQueryParams,
-  CreateFeedbackParams,
-  FeedbackAnchor,
-  FeedbackType,
-  ReadyOptions,
-  BlockerOptions,
-  FeedbackOptions,
-} from '../tools/types.js';