codekanban 0.19.0 → 0.21.0

package/packages/node-sdk/src/client.js

@@ -0,0 +1,323 @@
+import { buildAgentLaunchSpec } from './command-builder.js';
+import { CodeKanbanConfigError, CodeKanbanHttpError, CodeKanbanValidationError } from './errors.js';
+import { TerminalConnection } from './terminal-connection.js';
+import {
+  ensureOptionalString,
+  ensureString,
+  normalizeBaseUrl,
+  normalizeFsPath,
+  normalizeTerminalEnter,
+  pathBasename,
+  sleep,
+  toWsUrl,
+} from './utils.js';
+
+export class CodeKanbanClient {
+  constructor(options = {}) {
+    this.baseURL = normalizeBaseUrl(options.baseURL);
+    this.headers = { ...(options.headers || {}) };
+    this.fetchImpl = options.fetchImpl || globalThis.fetch;
+    this.WebSocketImpl = options.WebSocketImpl || globalThis.WebSocket;
+    if (!this.fetchImpl) {
+      throw new CodeKanbanConfigError('fetch implementation is unavailable');
+    }
+  }
+
+  async requestJson(path, options = {}) {
+    const method = options.method || 'GET';
+    const headers = { Accept: 'application/json', ...this.headers, ...(options.headers || {}) };
+    const request = {
+      method,
+      headers,
+    };
+    if (options.body !== undefined) {
+      request.body = JSON.stringify(options.body);
+      request.headers['Content-Type'] = 'application/json';
+    }
+    const response = await this.fetchImpl(new URL(path, this.baseURL), request);
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : null;
+    if (!response.ok) {
+      throw new CodeKanbanHttpError(`request failed with ${response.status}`, {
+        status: response.status,
+        method,
+        path,
+        body,
+      });
+    }
+    return body;
+  }
+
+  async listProjects() {
+    const response = await this.requestJson('/api/v1/projects');
+    return response?.items || [];
+  }
+
+  async getProject(projectId) {
+    ensureString(projectId, 'projectId');
+    const response = await this.requestJson(`/api/v1/projects/${projectId}`);
+    return response?.item;
+  }
+
+  async createProject({ path, name, description = '', worktreeBasePath, hidePath }) {
+    ensureString(path, 'path');
+    ensureString(name, 'name');
+    const response = await this.requestJson('/api/v1/projects/create', {
+      method: 'POST',
+      body: {
+        path,
+        name,
+        description,
+        worktreeBasePath,
+        hidePath,
+      },
+    });
+    return response?.item;
+  }
+
+  async listWorktrees(projectId) {
+    ensureString(projectId, 'projectId');
+    const response = await this.requestJson(`/api/v1/projects/${projectId}/worktrees`);
+    return response?.items || [];
+  }
+
+  async listTerminalSessions(projectId) {
+    ensureString(projectId, 'projectId');
+    const response = await this.requestJson(`/api/v1/projects/${projectId}/terminals`);
+    return response?.items || [];
+  }
+
+  async listAISessionsByProject(projectId) {
+    ensureString(projectId, 'projectId');
+    const response = await this.requestJson(`/api/v1/projects/${projectId}/ai-sessions`);
+    return response?.item || null;
+  }
+
+  async listAISessionsByPath(projectPath) {
+    ensureString(projectPath, 'path');
+    const response = await this.requestJson('/api/v1/ai-sessions/by-path', {
+      method: 'POST',
+      body: { path: projectPath },
+    });
+    return response?.item || null;
+  }
+
+  async getAISessionConversation({ id, sessionId, refresh = false }) {
+    const dbId = ensureOptionalString(id);
+    const rawSessionId = ensureOptionalString(sessionId);
+    if (!dbId && !rawSessionId) {
+      throw new CodeKanbanValidationError('id or sessionId is required');
+    }
+    if (refresh && !dbId) {
+      throw new CodeKanbanValidationError('refresh currently requires a database id');
+    }
+
+    if (dbId) {
+      const path = refresh ? `/api/v1/ai-sessions/${dbId}/refresh` : `/api/v1/ai-sessions/${dbId}/conversation`;
+      const response = await this.requestJson(path, { method: refresh ? 'POST' : 'GET' });
+      return response?.item || null;
+    }
+
+    const response = await this.requestJson(`/api/v1/ai-sessions/by-session-id/${rawSessionId}/conversation`);
+    return response?.item || null;
+  }
+
+  async getAISessionToolResult({ id, sessionId, toolUseId }) {
+    const dbId = ensureOptionalString(id);
+    const rawSessionId = ensureOptionalString(sessionId);
+    const resolvedToolUseId = ensureString(toolUseId, 'toolUseId');
+    if (!dbId && !rawSessionId) {
+      throw new CodeKanbanValidationError('id or sessionId is required');
+    }
+    const path = dbId
+      ? `/api/v1/ai-sessions/${dbId}/conversation/tool-results/${resolvedToolUseId}`
+      : `/api/v1/ai-sessions/by-session-id/${rawSessionId}/conversation/tool-results/${resolvedToolUseId}`;
+    const response = await this.requestJson(path);
+    return response?.item || null;
+  }
+
+  async createTerminalSession({ projectId, worktreeId, workingDir = '', title = '', rows = 0, cols = 0, taskId = '' }) {
+    ensureString(projectId, 'projectId');
+    ensureString(worktreeId, 'worktreeId');
+    const response = await this.requestJson(`/api/v1/projects/${projectId}/worktrees/${worktreeId}/terminals`, {
+      method: 'POST',
+      body: {
+        workingDir,
+        title,
+        rows,
+        cols,
+        taskId,
+      },
+    });
+    return response?.item;
+  }
+
+  async resolveProject({ projectId, path, ensureProject = true }) {
+    const resolvedProjectId = ensureOptionalString(projectId);
+    const resolvedPath = ensureOptionalString(path);
+
+    if (resolvedProjectId) {
+      const project = await this.getProject(resolvedProjectId);
+      return {
+        project,
+        matchedBy: 'projectId',
+      };
+    }
+
+    if (!resolvedPath) {
+      throw new CodeKanbanValidationError('projectId or path is required');
+    }
+
+    const target = normalizeFsPath(resolvedPath);
+    const projects = await this.listProjects();
+    const project = projects.find(item => normalizeFsPath(item.path) === target);
+    if (project) {
+      return {
+        project,
+        matchedBy: 'path',
+      };
+    }
+
+    if (!ensureProject) {
+      throw new CodeKanbanValidationError(`no CodeKanban project is registered for path: ${resolvedPath}`);
+    }
+
+    const created = await this.createProject({
+      path: resolvedPath,
+      name: pathBasename(resolvedPath),
+      description: '',
+    });
+    return {
+      project: created,
+      matchedBy: 'created',
+    };
+  }
+
+  async resolveWorktree({ projectId, worktreeId }) {
+    const project = ensureString(projectId, 'projectId');
+    const preferredWorktreeId = ensureOptionalString(worktreeId);
+    const worktrees = await this.listWorktrees(project);
+    if (worktrees.length === 0) {
+      throw new CodeKanbanValidationError(`no worktrees are available for project ${project}`);
+    }
+    if (preferredWorktreeId) {
+      const direct = worktrees.find(item => item.id === preferredWorktreeId);
+      if (!direct) {
+        throw new CodeKanbanValidationError(`worktree ${preferredWorktreeId} was not found in project ${project}`);
+      }
+      return direct;
+    }
+    return worktrees.find(item => item.isMain) || worktrees[0];
+  }
+
+  connectTerminal({ sessionId, wsPath, wsUrl }) {
+    const resolvedSessionId = ensureString(sessionId, 'sessionId');
+    const resolvedPath =
+      ensureOptionalString(wsUrl) || ensureOptionalString(wsPath) || `/api/v1/terminal/ws?sessionId=${resolvedSessionId}`;
+    const url = resolvedPath.startsWith('ws://') || resolvedPath.startsWith('wss://') ? resolvedPath : toWsUrl(this.baseURL, resolvedPath);
+
+    return new TerminalConnection({
+      sessionId: resolvedSessionId,
+      url,
+      WebSocketImpl: this.WebSocketImpl,
+    });
+  }
+
+  async listSessions({ projectId, path, includeTerminal = true, includeAI = true, ensureProject = true }) {
+    const { project, matchedBy } = await this.resolveProject({ projectId, path, ensureProject });
+
+    const [terminalSessions, aiSessions] = await Promise.all([
+      includeTerminal ? this.listTerminalSessions(project.id) : Promise.resolve([]),
+      includeAI
+        ? this.listAISessionsByProject(project.id)
+        : Promise.resolve({
+            hasClaudeCode: false,
+            hasCodex: false,
+            claudeSessions: [],
+            codexSessions: [],
+          }),
+    ]);
+
+    return {
+      project,
+      matchedBy,
+      terminalSessions,
+      aiSessions,
+    };
+  }
+
+  async startWorkflow(input = {}) {
+    const launch = buildAgentLaunchSpec(input);
+    const { project, matchedBy } = await this.resolveProject({
+      projectId: input.projectId,
+      path: input.path,
+      ensureProject: true,
+    });
+    const worktree = await this.resolveWorktree({
+      projectId: project.id,
+      worktreeId: input.worktreeId,
+    });
+
+    const terminal = await this.createTerminalSession({
+      projectId: project.id,
+      worktreeId: worktree.id,
+      workingDir: ensureOptionalString(input.workingDir) || worktree.path,
+      title: ensureOptionalString(input.title) || ensureOptionalString(input.prompt) || 'AI workflow',
+      taskId: ensureOptionalString(input.taskId),
+      rows: Number.isFinite(input.rows) ? input.rows : 0,
+      cols: Number.isFinite(input.cols) ? input.cols : 0,
+    });
+
+    const connection = this.connectTerminal({
+      sessionId: terminal.id,
+      wsPath: terminal.wsPath,
+      wsUrl: terminal.wsUrl,
+    });
+
+    await connection.waitForReady();
+    connection.sendInput(normalizeTerminalEnter(launch.command));
+    await sleep(500);
+    connection.sendInput(normalizeTerminalEnter(launch.prompt));
+    const metadata = await connection.waitForMetadata();
+
+    return {
+      project,
+      matchedBy,
+      worktree,
+      terminalSession: terminal,
+      agent: launch.agent,
+      profile: launch.profile,
+      command: launch.command,
+      prompt: launch.prompt,
+      promptAccepted: true,
+      aiSessionId: metadata?.aiSessionId,
+      connection,
+    };
+  }
+
+  async continueTerminalSession({ projectId, path, sessionId, prompt }) {
+    const resolvedSessionId = ensureString(sessionId, 'sessionId');
+    const resolvedPrompt = ensureString(prompt, 'prompt');
+
+    let project;
+    if (projectId || path) {
+      ({ project } = await this.resolveProject({ projectId, path, ensureProject: true }));
+      const sessions = await this.listTerminalSessions(project.id);
+      const exists = sessions.some(item => item.id === resolvedSessionId);
+      if (!exists) {
+        throw new CodeKanbanValidationError(`terminal session ${resolvedSessionId} does not belong to project ${project.id}`);
+      }
+    }
+
+    const connection = this.connectTerminal({ sessionId: resolvedSessionId });
+    await connection.waitForReady();
+    connection.sendInput(normalizeTerminalEnter(resolvedPrompt));
+    return {
+      project,
+      sessionId: resolvedSessionId,
+      prompt: resolvedPrompt,
+      promptAccepted: true,
+      connection,
+    };
+  }
+}

package/packages/node-sdk/src/command-builder.js

@@ -0,0 +1,129 @@
+import { CodeKanbanValidationError } from './errors.js';
+import { ensureArrayOfStrings, ensureOptionalString, toCommandString } from './utils.js';
+
+export const SANDBOX_MODES = ['read-only', 'workspace-write', 'danger-full-access'];
+export const APPROVAL_POLICIES = ['untrusted', 'on-request', 'never'];
+export const WORKFLOW_PROFILES = ['plan', 'standard', 'yolo'];
+export const AGENTS = ['codex', 'claude'];
+
+const KNOWN_STRUCTURED_FLAGS = new Set([
+  '-s',
+  '--sandbox',
+  '-a',
+  '--ask-for-approval',
+  '--add-dir',
+  '--dangerously-bypass-approvals-and-sandbox',
+]);
+
+export const PLAN_PROMPT_PREAMBLE = [
+  'You are starting in planning mode.',
+  'Inspect the project first, summarize the goal, and propose a concrete plan before making changes.',
+  'Do not mutate files until the user confirms execution or explicitly asks you to proceed immediately.',
+  'If additional directories or permissions are needed, call them out explicitly.',
+].join(' ');
+
+function validateEnum(value, allowed, fieldName) {
+  if (!value) {
+    return undefined;
+  }
+  if (!allowed.includes(value)) {
+    throw new CodeKanbanValidationError(`${fieldName} must be one of: ${allowed.join(', ')}`);
+  }
+  return value;
+}
+
+function detectStructuredFlagConflicts(extraArgs) {
+  const args = ensureArrayOfStrings(extraArgs, 'extraArgs');
+  const conflicts = [];
+  for (const arg of args) {
+    if (KNOWN_STRUCTURED_FLAGS.has(arg)) {
+      conflicts.push(arg);
+    }
+  }
+  return conflicts;
+}
+
+export function composeWorkflowPrompt({ profile = 'standard', prompt }) {
+  const userPrompt = String(prompt || '').trim();
+  if (!userPrompt) {
+    throw new CodeKanbanValidationError('prompt is required');
+  }
+  if (profile === 'plan') {
+    return `${PLAN_PROMPT_PREAMBLE}\n\nUser request:\n${userPrompt}`;
+  }
+  return userPrompt;
+}
+
+export function buildAgentLaunchSpec(options = {}) {
+  const agent = validateEnum(options.agent || 'codex', AGENTS, 'agent') || 'codex';
+  const profile = validateEnum(options.profile || 'standard', WORKFLOW_PROFILES, 'profile') || 'standard';
+  const extraArgs = ensureArrayOfStrings(options.extraArgs, 'extraArgs');
+
+  if (agent === 'claude') {
+    if (profile !== 'standard') {
+      throw new CodeKanbanValidationError('claude only supports the standard profile in v1');
+    }
+    if (options.permissions) {
+      throw new CodeKanbanValidationError('structured permissions are only supported for codex in v1');
+    }
+    const argv = ['claude', ...extraArgs];
+    return {
+      agent,
+      profile,
+      argv,
+      command: toCommandString(argv),
+      prompt: composeWorkflowPrompt({ profile, prompt: options.prompt }),
+    };
+  }
+
+  const permissions = options.permissions || {};
+  const conflicts = detectStructuredFlagConflicts(extraArgs);
+  if (
+    conflicts.length > 0 &&
+    (permissions.sandbox ||
+      permissions.approvalPolicy ||
+      (permissions.addDirs && permissions.addDirs.length > 0) ||
+      profile === 'yolo')
+  ) {
+    throw new CodeKanbanValidationError(`extraArgs conflicts with structured permissions: ${conflicts.join(', ')}`);
+  }
+
+  if (profile === 'yolo') {
+    if (permissions.sandbox || permissions.approvalPolicy || (permissions.addDirs && permissions.addDirs.length > 0)) {
+      throw new CodeKanbanValidationError('yolo does not accept structured sandbox, approval, or addDirs overrides');
+    }
+    const argv = ['codex', '--dangerously-bypass-approvals-and-sandbox', ...extraArgs];
+    return {
+      agent,
+      profile,
+      argv,
+      command: toCommandString(argv),
+      prompt: composeWorkflowPrompt({ profile, prompt: options.prompt }),
+    };
+  }
+
+  const sandbox =
+    validateEnum(ensureOptionalString(permissions.sandbox) || 'workspace-write', SANDBOX_MODES, 'permissions.sandbox') ||
+    'workspace-write';
+  const approvalPolicy =
+    validateEnum(
+      ensureOptionalString(permissions.approvalPolicy) || 'on-request',
+      APPROVAL_POLICIES,
+      'permissions.approvalPolicy',
+    ) || 'on-request';
+  const addDirs = ensureArrayOfStrings(permissions.addDirs, 'permissions.addDirs');
+
+  const argv = ['codex', '-s', sandbox, '-a', approvalPolicy];
+  for (const dir of addDirs) {
+    argv.push('--add-dir', dir);
+  }
+  argv.push(...extraArgs);
+
+  return {
+    agent,
+    profile,
+    argv,
+    command: toCommandString(argv),
+    prompt: composeWorkflowPrompt({ profile, prompt: options.prompt }),
+  };
+}

package/packages/node-sdk/src/errors.js

@@ -0,0 +1,28 @@
+export class CodeKanbanError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = options.name || this.constructor.name;
+    if (options.cause) {
+      this.cause = options.cause;
+    }
+    for (const [key, value] of Object.entries(options)) {
+      if (key === 'name' || key === 'cause') {
+        continue;
+      }
+      this[key] = value;
+    }
+  }
+}
+
+export class CodeKanbanConfigError extends CodeKanbanError {}
+export class CodeKanbanValidationError extends CodeKanbanError {}
+
+export class CodeKanbanHttpError extends CodeKanbanError {
+  constructor(message, options = {}) {
+    super(message, { ...options, name: 'CodeKanbanHttpError' });
+    this.status = options.status ?? 500;
+    this.method = options.method ?? 'GET';
+    this.path = options.path ?? '';
+    this.body = options.body;
+  }
+}

package/packages/node-sdk/src/index.js

@@ -0,0 +1,17 @@
+export { CodeKanbanClient } from './client.js';
+export {
+  AGENTS,
+  APPROVAL_POLICIES,
+  PLAN_PROMPT_PREAMBLE,
+  SANDBOX_MODES,
+  WORKFLOW_PROFILES,
+  buildAgentLaunchSpec,
+  composeWorkflowPrompt,
+} from './command-builder.js';
+export {
+  CodeKanbanConfigError,
+  CodeKanbanError,
+  CodeKanbanHttpError,
+  CodeKanbanValidationError,
+} from './errors.js';
+export { TerminalConnection } from './terminal-connection.js';

package/packages/node-sdk/src/terminal-connection.js

@@ -0,0 +1,133 @@
+import { CodeKanbanConfigError, CodeKanbanError, CodeKanbanValidationError } from './errors.js';
+
+function decodeJsonMessage(raw) {
+  const text = typeof raw === 'string' ? raw : String(raw ?? '');
+  return JSON.parse(text);
+}
+
+export class TerminalConnection {
+  constructor({ sessionId, url, WebSocketImpl }) {
+    if (!sessionId) {
+      throw new CodeKanbanValidationError('sessionId is required');
+    }
+    if (!url) {
+      throw new CodeKanbanValidationError('url is required');
+    }
+    const Socket = WebSocketImpl || globalThis.WebSocket;
+    if (!Socket) {
+      throw new CodeKanbanConfigError('WebSocket implementation is unavailable');
+    }
+
+    this.sessionId = sessionId;
+    this.url = url;
+    this.messages = [];
+    this.lastMetadata = undefined;
+    this.readyMessage = undefined;
+    this._listeners = new Map();
+
+    this.socket = new Socket(url);
+    this._readyResolve = null;
+    this._readyReject = null;
+    this._readyPromise = new Promise((resolve, reject) => {
+      this._readyResolve = resolve;
+      this._readyReject = reject;
+    });
+
+    this.socket.addEventListener('message', event => {
+      const payload = decodeJsonMessage(event.data);
+      this.messages.push(payload);
+      if (payload.type === 'metadata' && payload.metadata) {
+        this.lastMetadata = payload.metadata;
+      }
+      if (payload.type === 'ready') {
+        this.readyMessage = payload;
+        this._readyResolve?.(payload);
+      }
+      this._emit('message', payload);
+      this._emit(payload.type, payload);
+    });
+
+    this.socket.addEventListener('error', event => {
+      const error = new CodeKanbanError('terminal websocket error', { event });
+      this._readyReject?.(error);
+      this._emit('error', error);
+    });
+
+    this.socket.addEventListener('close', event => {
+      this._emit('close', event);
+    });
+  }
+
+  on(type, handler) {
+    const existing = this._listeners.get(type) || new Set();
+    existing.add(handler);
+    this._listeners.set(type, existing);
+    return () => this.off(type, handler);
+  }
+
+  off(type, handler) {
+    const existing = this._listeners.get(type);
+    if (!existing) {
+      return;
+    }
+    existing.delete(handler);
+  }
+
+  _emit(type, payload) {
+    const existing = this._listeners.get(type);
+    if (!existing) {
+      return;
+    }
+    for (const handler of existing) {
+      handler(payload);
+    }
+  }
+
+  async waitForReady(timeoutMs = 8000) {
+    if (this.readyMessage) {
+      return this.readyMessage;
+    }
+    return await Promise.race([
+      this._readyPromise,
+      new Promise((_, reject) => {
+        setTimeout(
+          () => reject(new CodeKanbanValidationError(`terminal session ${this.sessionId} did not become ready in time`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  }
+
+  sendJson(payload) {
+    this.socket.send(JSON.stringify(payload));
+  }
+
+  sendInput(data) {
+    this.sendJson({ type: 'input', data });
+  }
+
+  resize(cols, rows) {
+    this.sendJson({ type: 'resize', cols, rows });
+  }
+
+  close() {
+    this.sendJson({ type: 'close' });
+    this.socket.close();
+  }
+
+  async waitForMetadata(timeoutMs = 1500) {
+    if (this.lastMetadata) {
+      return this.lastMetadata;
+    }
+    return await new Promise(resolve => {
+      const cleanup = this.on('metadata', payload => {
+        cleanup();
+        resolve(payload.metadata);
+      });
+      setTimeout(() => {
+        cleanup();
+        resolve(this.lastMetadata);
+      }, timeoutMs);
+    });
+  }
+}