cccc-sdk 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+# @cccc/sdk
+
+CCCC Client SDK for Node.js - IPC client for CCCC daemon.
+
+## Installation
+
+```bash
+npm install @cccc/sdk
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- CCCC daemon running locally
+
+## Quick Start
+
+```typescript
+import { CCCCClient } from '@cccc/sdk';
+
+const client = new CCCCClient();
+
+// Check daemon is running
+const isRunning = await client.ping();
+console.log('Daemon running:', isRunning);
+
+// List all groups
+const groups = await client.groups.list();
+console.log('Groups:', groups);
+```
+
+## API Overview
+
+### Groups
+
+```typescript
+// List groups
+const groups = await client.groups.list();
+
+// Get group info
+const group = await client.groups.get('g_abc123');
+
+// Create group
+const newGroup = await client.groups.create({
+  title: 'My Project',
+  topic: 'Building something awesome',
+  url: '/path/to/project',
+});
+
+// Start/Stop group
+await client.groups.start('g_abc123');
+await client.groups.stop('g_abc123');
+
+// Set group state
+await client.groups.setState('g_abc123', 'active', 'user');
+```
+
+### Actors
+
+```typescript
+// List actors
+const actors = await client.actors.list('g_abc123');
+
+// Add actor
+const actor = await client.actors.add('g_abc123', 'user', {
+  actor_id: 'agent-1',
+  runtime: 'claude',
+  runner: 'pty',
+  title: 'Claude Agent',
+});
+
+// Start/Stop/Restart actor
+await client.actors.start('g_abc123', 'agent-1', 'user');
+await client.actors.stop('g_abc123', 'agent-1', 'user');
+await client.actors.restart('g_abc123', 'agent-1', 'user');
+
+// Remove actor
+await client.actors.remove('g_abc123', 'agent-1', 'user');
+```
+
+### Messages
+
+```typescript
+// Send message
+const event = await client.messages.send('g_abc123', 'user', {
+  text: 'Hello agents!',
+  to: ['agent-1', 'agent-2'],
+});
+
+// Reply to message
+await client.messages.reply('g_abc123', 'user', {
+  event_id: 'abc123',
+  text: 'Got it!',
+});
+```
+
+### Inbox
+
+```typescript
+// List inbox messages
+const messages = await client.inbox.list('g_abc123', 'agent-1', {
+  kind_filter: 'chat',
+  limit: 50,
+});
+
+// Mark as read
+await client.inbox.markRead('g_abc123', 'agent-1', 'event_id');
+
+// Mark all as read
+await client.inbox.markAllRead('g_abc123', 'agent-1');
+```
+
+### Context
+
+```typescript
+// Get context
+const ctx = await client.context.get('g_abc123');
+console.log('Vision:', ctx.vision);
+console.log('Milestones:', ctx.milestones);
+
+// Update vision
+await client.vision.update('g_abc123', 'Build the best product');
+
+// Update sketch
+await client.sketch.update('g_abc123', '## Architecture\n...');
+```
+
+### Tasks
+
+```typescript
+// List tasks
+const tasks = await client.tasks.list('g_abc123');
+
+// Create task
+const task = await client.tasks.create('g_abc123', {
+  name: 'Implement feature X',
+  goal: 'Feature X works correctly',
+  steps: [
+    { name: 'Design API', acceptance: 'API spec documented' },
+    { name: 'Implement', acceptance: 'Code written and tested' },
+    { name: 'Review', acceptance: 'PR approved' },
+  ],
+});
+
+// Update task status
+await client.tasks.update('g_abc123', {
+  task_id: task.id,
+  status: 'active',
+});
+```
+
+### Milestones
+
+```typescript
+// Create milestone
+const milestone = await client.milestones.create('g_abc123', {
+  name: 'MVP',
+  description: 'Minimum viable product',
+});
+
+// Complete milestone
+await client.milestones.complete('g_abc123', milestone.id, 'Shipped!');
+```
+
+## Error Handling
+
+```typescript
+import { CCCCClient, CCCCError } from '@cccc/sdk';
+
+const client = new CCCCClient();
+
+try {
+  await client.groups.get('invalid-id');
+} catch (error) {
+  if (error instanceof CCCCError) {
+    console.error('CCCC Error:', error.code, error.message);
+    // Handle specific errors
+    switch (error.code) {
+      case 'DAEMON_NOT_RUNNING':
+        console.error('Please start CCCC daemon first');
+        break;
+      case 'GROUP_NOT_FOUND':
+        console.error('Group does not exist');
+        break;
+    }
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const client = new CCCCClient({
+  // Custom CCCC home directory (default: ~/.cccc)
+  ccccHome: '/custom/path/.cccc',
+  // Request timeout in ms (default: 60000)
+  timeoutMs: 30000,
+});
+```
+
+## Low-level API
+
+For operations not covered by the high-level API:
+
+```typescript
+// Direct daemon call
+const response = await client.call('custom_op', {
+  arg1: 'value1',
+  arg2: 'value2',
+});
+
+if (response.ok) {
+  console.log('Result:', response.result);
+} else {
+  console.error('Error:', response.error);
+}
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,262 @@
+/**
+ * CCCC Client SDK
+ *
+ * High-level API for interacting with CCCC daemon
+ */
+import { type TransportOptions } from './transport.js';
+import { type DaemonResponse } from './types/ipc.js';
+import type { Actor, ActorAddOptions, GroupState, HeadlessState } from './types/actor.js';
+import type { GroupInfo, GroupCreateOptions, GroupUpdatePatch } from './types/group.js';
+import type { SendMessageOptions, ReplyMessageOptions, InboxMessage, InboxListOptions } from './types/message.js';
+import type { Event } from './types/event.js';
+import type { Context, ContextSyncOp, Task, TaskCreateOptions, TaskUpdateOptions, Milestone, MilestoneCreateOptions } from './types/context.js';
+export interface CCCCClientOptions extends TransportOptions {
+}
+/**
+ * Groups API
+ */
+declare class GroupsAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * List all groups
+     */
+    list(): Promise<GroupInfo[]>;
+    /**
+     * Get group info
+     */
+    get(groupId: string): Promise<GroupInfo>;
+    /**
+     * Create a new group
+     */
+    create(options: GroupCreateOptions): Promise<GroupInfo>;
+    /**
+     * Set group state
+     */
+    setState(groupId: string, state: GroupState, by: string): Promise<void>;
+    /**
+     * Start group (activate all enabled actors)
+     */
+    start(groupId: string): Promise<void>;
+    /**
+     * Stop group (stop all actors)
+     */
+    stop(groupId: string): Promise<void>;
+    /**
+     * Update group
+     */
+    update(groupId: string, patch: GroupUpdatePatch): Promise<void>;
+    /**
+     * Delete group
+     */
+    delete(groupId: string): Promise<void>;
+}
+/**
+ * Actors API
+ */
+declare class ActorsAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * List actors in a group
+     */
+    list(groupId: string): Promise<Actor[]>;
+    /**
+     * Add an actor to a group
+     */
+    add(groupId: string, by: string, options: ActorAddOptions): Promise<Actor>;
+    /**
+     * Start an actor
+     */
+    start(groupId: string, actorId: string, by: string): Promise<void>;
+    /**
+     * Stop an actor
+     */
+    stop(groupId: string, actorId: string, by: string): Promise<void>;
+    /**
+     * Restart an actor
+     */
+    restart(groupId: string, actorId: string, by: string): Promise<void>;
+    /**
+     * Remove an actor
+     */
+    remove(groupId: string, actorId: string, by: string): Promise<void>;
+}
+/**
+ * Messages API
+ */
+declare class MessagesAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * Send a message
+     */
+    send(groupId: string, by: string, options: SendMessageOptions): Promise<Event>;
+    /**
+     * Reply to a message
+     */
+    reply(groupId: string, by: string, options: ReplyMessageOptions): Promise<Event>;
+}
+/**
+ * Inbox API
+ */
+declare class InboxAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * List inbox messages
+     */
+    list(groupId: string, actorId: string, options?: InboxListOptions): Promise<InboxMessage[]>;
+    /**
+     * Mark messages as read up to event_id
+     */
+    markRead(groupId: string, actorId: string, eventId: string): Promise<void>;
+    /**
+     * Mark all messages as read
+     */
+    markAllRead(groupId: string, actorId: string): Promise<void>;
+}
+/**
+ * Context API
+ */
+declare class ContextAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * Get project context
+     */
+    get(groupId: string): Promise<Context>;
+    /**
+     * Sync context with batch operations
+     */
+    sync(groupId: string, ops: ContextSyncOp[], dryRun?: boolean): Promise<Record<string, unknown>>;
+}
+/**
+ * Tasks API
+ */
+declare class TasksAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * List tasks
+     */
+    list(groupId: string, includeArchived?: boolean): Promise<Task[]>;
+    /**
+     * Create a task
+     */
+    create(groupId: string, options: TaskCreateOptions): Promise<Task>;
+    /**
+     * Update a task
+     */
+    update(groupId: string, options: TaskUpdateOptions): Promise<Task>;
+}
+/**
+ * Milestones API
+ */
+declare class MilestonesAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * Create a milestone
+     */
+    create(groupId: string, options: MilestoneCreateOptions): Promise<Milestone>;
+    /**
+     * Complete a milestone
+     */
+    complete(groupId: string, milestoneId: string, outcomes: string): Promise<void>;
+}
+/**
+ * Vision API
+ */
+declare class VisionAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * Update project vision
+     */
+    update(groupId: string, vision: string): Promise<void>;
+}
+/**
+ * Sketch API
+ */
+declare class SketchAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * Update execution sketch
+     */
+    update(groupId: string, sketch: string): Promise<void>;
+}
+/**
+ * Headless API for MCP-driven actors
+ */
+declare class HeadlessAPI {
+    private client;
+    constructor(client: CCCCClient);
+    /**
+     * Get headless session status
+     */
+    status(groupId: string, actorId: string): Promise<HeadlessState>;
+    /**
+     * Set headless session status
+     */
+    setStatus(groupId: string, actorId: string, status: 'idle' | 'working' | 'waiting' | 'stopped', taskId?: string): Promise<void>;
+    /**
+     * Acknowledge processed message
+     */
+    ackMessage(groupId: string, actorId: string, messageId: string): Promise<void>;
+}
+/**
+ * CCCC Client
+ *
+ * Main entry point for SDK
+ *
+ * @example
+ * ```typescript
+ * const client = new CCCCClient();
+ *
+ * // List all groups
+ * const groups = await client.groups.list();
+ *
+ * // Add an actor
+ * await client.actors.add(groupId, 'user', {
+ *   actor_id: 'agent-1',
+ *   runtime: 'claude',
+ *   runner: 'pty'
+ * });
+ *
+ * // Send a message
+ * await client.messages.send(groupId, 'user', {
+ *   text: 'Hello agents!',
+ *   to: ['agent-1']
+ * });
+ * ```
+ */
+export declare class CCCCClient {
+    private options;
+    readonly groups: GroupsAPI;
+    readonly actors: ActorsAPI;
+    readonly messages: MessagesAPI;
+    readonly inbox: InboxAPI;
+    readonly context: ContextAPI;
+    readonly tasks: TasksAPI;
+    readonly milestones: MilestonesAPI;
+    readonly vision: VisionAPI;
+    readonly sketch: SketchAPI;
+    readonly headless: HeadlessAPI;
+    constructor(options?: CCCCClientOptions);
+    /**
+     * Ping daemon to check if it's running
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Low-level daemon call
+     */
+    call(op: string, args: Record<string, unknown>): Promise<DaemonResponse>;
+    /**
+     * Shutdown the daemon
+     */
+    shutdown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map