codekanban 0.31.0 → 0.33.0

package/packages/codekanban-cli/src/index.js

@@ -0,0 +1,13 @@
+import { runCli, createHelpText } from './runtime.js';
+
+export * from './core.js';
+export { runCodeKanbanCli };
+
+import { runCodeKanbanCliWithRuntime } from './core.js';
+
+async function runCodeKanbanCli(argv, options = {}) {
+  return await runCodeKanbanCliWithRuntime(argv, {
+    runCli,
+    createHelpText,
+  }, options);
+}

package/packages/{node-sdk/src/cli.js → codekanban-cli/src/runtime.js}

@@ -1,6 +1,8 @@
-import { CodeKanbanClient } from './client.js';
-import { buildAgentLaunchSpec } from './command-builder.js';
-import { createJsonOutput } from './utils.js';
+import { CodeKanbanClient, buildAgentLaunchSpec } from '@codekanban/sdk';
+
+function createJsonOutput(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
 
 function readFlagValue(argv, index, flag) {
   const value = argv[index + 1];
@@ -37,12 +39,16 @@ function parseCliArgs(argv) {
   const flags = {
     addDirs: [],
     attachmentIds: [],
+    deleteFilesBefore: [],
     extraArgs: [],
+    readFilesAfter: [],
     includeTerminal: true,
     includeAI: true,
     refresh: false,
     clearExisting: false,
     raw: false,
+    strictCwd: false,
+    ifExists: false,
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -161,6 +167,10 @@ function parseCliArgs(argv) {
         flags.groupId = readFlagValue(argv, index, token);
         index += 1;
         break;
+      case '--scope-id':
+        flags.scopeId = readFlagValue(argv, index, token);
+        index += 1;
+        break;
       case '--file':
         flags.file = readFlagValue(argv, index, token);
         index += 1;
@@ -173,6 +183,10 @@ function parseCliArgs(argv) {
         flags.answersJson = readFlagValue(argv, index, token);
         index += 1;
         break;
+      case '--answer-strategy':
+        flags.answerStrategy = readFlagValue(argv, index, token);
+        index += 1;
+        break;
       case '--prev-session-id':
         flags.prevSessionId = readFlagValue(argv, index, token);
         index += 1;
@@ -189,6 +203,30 @@ function parseCliArgs(argv) {
         flags.maxEvents = readFlagValue(argv, index, token);
         index += 1;
         break;
+      case '--interval-ms':
+        flags.intervalMs = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--settle-ms':
+        flags.settleMs = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--timeout-ms':
+        flags.timeoutMs = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--until':
+        flags.until = readFlagValue(argv, index, token);
+        index += 1;
+        break;
+      case '--delete-file-before':
+        flags.deleteFilesBefore.push(readFlagValue(argv, index, token));
+        index += 1;
+        break;
+      case '--read-file-after':
+        flags.readFilesAfter.push(readFlagValue(argv, index, token));
+        index += 1;
+        break;
       case '--refresh':
         flags.refresh = true;
         break;
@@ -198,6 +236,12 @@ function parseCliArgs(argv) {
       case '--raw':
         flags.raw = true;
         break;
+      case '--strict-cwd':
+        flags.strictCwd = true;
+        break;
+      case '--if-exists':
+        flags.ifExists = true;
+        break;
       case '--no-terminal':
         flags.includeTerminal = false;
         break;
@@ -215,6 +259,39 @@ function parseCliArgs(argv) {
   };
 }
 
+export function createHelpText(commandName = 'codekanban-cli') {
+  return `${commandName} - CodeKanban command runtime
+
+Usage:
+  ${commandName} <scope> <action> [options]
+
+Scopes:
+  workflow     start, command
+  session      list, conversation, tool-result
+  terminal     continue
+  file         scopes, read, delete
+  web-session  list, create, connect, snapshot, history, sync,
+               state, answer-pending, execute-plan, wait, run,
+               archived, archive, unarchive, rename, close, delete,
+               runtime-config, command-group, attach, send, approve,
+               reject, user-input, set-model, set-reasoning,
+               set-workflow, set-permission, set-agent, move, watch
+
+Common options:
+  --base-url <url>      CodeKanban server base URL
+  --project-id <id>     Project identifier
+  --path <path>         Local project path
+  --session-id <id>     Session identifier
+  --help                Show this help text
+
+Examples:
+  ${commandName} session list --base-url http://127.0.0.1:3007 --path D:/repo
+  ${commandName} web-session state --base-url http://127.0.0.1:3007 --path D:/repo --session-id <id>
+  ${commandName} web-session run --base-url http://127.0.0.1:3007 --path D:/repo --agent codex --text "Create notes/123.md" --delete-file-before notes/123.md --read-file-after notes/123.md --strict-cwd
+`;
+
+}
+
 function buildPermissions(flags) {
   const permissions = {};
   if (flags.sandbox) {
@@ -230,6 +307,9 @@ function buildPermissions(flags) {
 }
 
 function sanitizeConnection(value) {
+  if (Array.isArray(value)) {
+    return value.map(item => sanitizeConnection(item));
+  }
   if (!value || typeof value !== 'object') {
     return value;
   }
@@ -318,15 +398,223 @@ async function watchWebSession(client, flags, stdout) {
   }
 }
 
+const STRICT_CWD_INSTRUCTION =
+  'Stay strictly inside the current working directory. Do not search sibling directories, parent directories, or nearby repositories unless the user explicitly asks.';
+
+function normalizeChoiceLabel(value) {
+  return String(value || '').trim();
+}
+
+function buildAutoUserInputAnswers(questions = [], strategy = 'prefer-second-or-text') {
+  const normalizedStrategy = String(strategy || 'prefer-second-or-text').trim().toLowerCase();
+  if (!['prefer-second-or-text', 'prefer-second-or-first'].includes(normalizedStrategy)) {
+    throw new Error(`unsupported answer strategy: ${strategy}`);
+  }
+
+  const answers = {};
+  for (const question of Array.isArray(questions) ? questions : []) {
+    const questionId = normalizeChoiceLabel(question?.id);
+    if (!questionId) {
+      continue;
+    }
+    const options = Array.isArray(question?.options)
+      ? question.options.map(option => normalizeChoiceLabel(option?.label)).filter(Boolean)
+      : [];
+    if (options[1]) {
+      answers[questionId] = [options[1]];
+      continue;
+    }
+    if (normalizedStrategy === 'prefer-second-or-first' && options[0]) {
+      answers[questionId] = [options[0]];
+      continue;
+    }
+    answers[questionId] = [question?.isSecret ? 'redacted' : 'continue'];
+  }
+  return answers;
+}
+
+function normalizeUntil(value) {
+  const raw = String(value || '').trim();
+  if (!raw) {
+    return 'done';
+  }
+  const phases = raw
+    .split(',')
+    .map(entry => entry.trim())
+    .filter(Boolean);
+  if (phases.length === 0) {
+    return 'done';
+  }
+  return phases.length === 1 ? phases[0] : phases;
+}
+
+function withStrictCwdPrompt(text, strictCwd) {
+  const body = String(text || '').trim();
+  if (!strictCwd) {
+    return body;
+  }
+  return body
+    ? `${STRICT_CWD_INSTRUCTION}
+
+${body}`
+    : STRICT_CWD_INSTRUCTION;
+}
+
+async function answerPendingWithStrategy(client, flags) {
+  const answers = flags.answersJson
+    ? parseJsonFlag(flags.answersJson, 'answersJson')
+    : buildAutoUserInputAnswers([], flags.answerStrategy);
+  const state = await client.getWebSessionState({
+    projectId: flags.projectId,
+    path: flags.path,
+    sessionId: flags.sessionId,
+    limit: parseIntegerFlag(flags.limit, 'limit'),
+  });
+  if (!state.pendingUserInput) {
+    throw new Error(`web session ${flags.sessionId} has no pending user input`);
+  }
+  const resolvedAnswers = flags.answersJson
+    ? answers
+    : buildAutoUserInputAnswers(
+        state.pendingUserInput.questions,
+        flags.answerStrategy,
+      );
+  return await client.answerPendingUserInput({
+    projectId: flags.projectId,
+    path: flags.path,
+    sessionId: flags.sessionId,
+    answers: resolvedAnswers,
+    limit: parseIntegerFlag(flags.limit, 'limit'),
+  });
+}
+
+async function maybeDeleteFilesBefore(client, flags, sessionProjectId) {
+  const deleted = [];
+  for (const filePath of flags.deleteFilesBefore) {
+    const result = await client.deleteProjectFiles({
+      projectId: sessionProjectId || flags.projectId,
+      path: sessionProjectId ? undefined : flags.path,
+      scopeId: flags.scopeId,
+      paths: [filePath],
+    });
+    deleted.push({ path: filePath, result });
+  }
+  return deleted;
+}
+
+async function readFilesAfter(client, flags, sessionProjectId) {
+  const files = [];
+  for (const filePath of flags.readFilesAfter) {
+    const item = await client.readProjectFileText({
+      projectId: sessionProjectId || flags.projectId,
+      path: sessionProjectId ? undefined : flags.path,
+      scopeId: flags.scopeId,
+      filePath,
+    });
+    files.push(item);
+  }
+  return files;
+}
+
+async function runWebSessionFlow(client, flags) {
+  const intervalMs = parseIntegerFlag(flags.intervalMs, 'intervalMs') || 2000;
+  const timeoutMs = parseIntegerFlag(flags.timeoutMs, 'timeoutMs') || 120000;
+  const settleMs = parseIntegerFlag(flags.settleMs, 'settleMs') || 2000;
+
+  let session = null;
+  let sessionId = flags.sessionId;
+  let sessionProjectId = flags.projectId;
+  const initialPrompt = withStrictCwdPrompt(flags.text || flags.prompt, flags.strictCwd);
+
+  if (!sessionId) {
+    if (!initialPrompt) {
+      throw new Error('web-session run requires --session-id or an initial --text/--prompt');
+    }
+    session = await client.createWebSession({
+      projectId: flags.projectId,
+      path: flags.path,
+      worktreeId: flags.worktreeId,
+      agent: flags.agent || 'codex',
+      model: flags.model,
+      reasoningEffort: flags.reasoningEffort,
+      workflowMode: flags.workflowMode || 'plan',
+      permissionLevel: flags.permissionLevel,
+      permissionMode: flags.permissionMode,
+      title: flags.title,
+    });
+    sessionId = session?.id;
+    sessionProjectId = session?.projectId || sessionProjectId;
+  }
+
+  if (!sessionId) {
+    throw new Error('unable to resolve a web session id');
+  }
+
+  const deletedBefore = await maybeDeleteFilesBefore(client, flags, sessionProjectId);
+
+  if (initialPrompt) {
+    await client.sendWebSessionMessage({
+      sessionId,
+      text: initialPrompt,
+      attachmentIds: flags.attachmentIds,
+      mode: flags.mode,
+    });
+  }
+
+  const flow = await client.runWebSessionUntilDone({
+    projectId: sessionProjectId || flags.projectId,
+    path: sessionProjectId ? undefined : flags.path,
+    sessionId,
+    until: normalizeUntil(flags.until),
+    intervalMs,
+    timeoutMs,
+    limit: parseIntegerFlag(flags.limit, 'limit'),
+    settleMs,
+    answerStrategy: flags.answerStrategy || 'prefer-second-or-text',
+    autoExecutePlan: true,
+    executePlanPrompt: withStrictCwdPrompt('Implement the plan.', flags.strictCwd),
+  });
+
+  if (flow.stopReason === 'needs_approval') {
+    throw new Error('web-session run stopped on a pending approval; use web-session approve or reject explicitly');
+  }
+  if (flow.stopReason === 'needs_user_input') {
+    throw new Error('web-session run stopped on a pending user input; use web-session answer-pending explicitly');
+  }
+  if (flow.stopReason === 'needs_execute_plan') {
+    throw new Error('web-session run stopped before executing the latest plan; use web-session execute-plan explicitly');
+  }
+  if (flow.stopReason === 'timeout') {
+    throw new Error(`web-session run timed out after ${timeoutMs}ms`);
+  }
+
+  const filesAfter = await readFilesAfter(client, flags, sessionProjectId);
+  return {
+    session: session || { id: sessionId, projectId: sessionProjectId || flags.projectId },
+    deletedBefore,
+    actions: flow.actions,
+    finalState: flow.finalState,
+    filesAfter,
+  };
+}
+
+
 export async function runCli(argv, options = {}) {
   const stdout = options.stdout || process.stdout;
   const stderr = options.stderr || process.stderr;
+  const commandName = options.commandName || 'codekanban-cli';
 
   try {
+    if (argv.includes('--help') || argv.includes('-h')) {
+      stdout.write(createHelpText(commandName));
+      return 0;
+    }
+
     const { positionals, flags } = parseCliArgs(argv);
     const [scope, action] = positionals;
     if (!scope || !action) {
-      throw new Error('usage: <workflow|session|terminal|web-session> <action> --base-url <url> [...]');
+      stdout.write(createHelpText(commandName));
+      return 0;
     }
 
     if (scope === 'workflow' && action === 'command') {
@@ -341,11 +629,20 @@ export async function runCli(argv, options = {}) {
       return 0;
     }
 
+    if (!flags.baseURL && options.defaultBaseURL) {
+      flags.baseURL = options.defaultBaseURL;
+    }
+
     if (!flags.baseURL) {
       throw new Error('--base-url is required');
     }
 
-    const client = new CodeKanbanClient({ baseURL: flags.baseURL });
+    const client =
+      options.clientFactory?.({ baseURL: flags.baseURL, flags }) ||
+      new CodeKanbanClient({
+        baseURL: flags.baseURL,
+        ...(options.clientOptions || {}),
+      });
     let result;
 
     if (scope === 'workflow' && action === 'start') {
@@ -387,6 +684,25 @@ export async function runCli(argv, options = {}) {
         sessionId: flags.sessionId,
         prompt: flags.prompt,
       });
+    } else if (scope === 'file' && action === 'scopes') {
+      result = await client.listProjectFileScopes({
+        projectId: flags.projectId,
+        path: flags.path,
+      });
+    } else if (scope === 'file' && action === 'read') {
+      result = await client.readProjectFileText({
+        projectId: flags.projectId,
+        path: flags.path,
+        scopeId: flags.scopeId,
+        filePath: flags.file,
+      });
+    } else if (scope === 'file' && action === 'delete') {
+      result = await client.deleteProjectFiles({
+        projectId: flags.projectId,
+        path: flags.path,
+        scopeId: flags.scopeId,
+        paths: [flags.file],
+      });
     } else if (scope === 'web-session' && action === 'list') {
       result = await client.listWebSessions({
         projectId: flags.projectId,
@@ -430,6 +746,36 @@ export async function runCli(argv, options = {}) {
         mode: flags.mode,
         clearExisting: flags.clearExisting,
       });
+    } else if (scope === 'web-session' && action === 'state') {
+      result = await client.getWebSessionState({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+        limit: parseIntegerFlag(flags.limit, 'limit'),
+      });
+    } else if (scope === 'web-session' && action === 'answer-pending') {
+      result = await answerPendingWithStrategy(client, flags);
+    } else if (scope === 'web-session' && action === 'execute-plan') {
+      result = await client.executeLatestPlan({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+        prompt: withStrictCwdPrompt('Implement the plan.', flags.strictCwd),
+        limit: parseIntegerFlag(flags.limit, 'limit'),
+      });
+    } else if (scope === 'web-session' && action === 'wait') {
+      result = await client.waitForWebSessionState({
+        projectId: flags.projectId,
+        path: flags.path,
+        sessionId: flags.sessionId,
+        until: normalizeUntil(flags.until),
+        intervalMs: parseIntegerFlag(flags.intervalMs, 'intervalMs') || 2000,
+        timeoutMs: parseIntegerFlag(flags.timeoutMs, 'timeoutMs') || 120000,
+        limit: parseIntegerFlag(flags.limit, 'limit'),
+        settleMs: parseIntegerFlag(flags.settleMs, 'settleMs') || 0,
+      });
+    } else if (scope === 'web-session' && action === 'run') {
+      result = await runWebSessionFlow(client, flags);
     } else if (scope === 'web-session' && action === 'archive') {
       result = await client.archiveWebSession({
         projectId: flags.projectId,
@@ -479,8 +825,9 @@ export async function runCli(argv, options = {}) {
     } else if (scope === 'web-session' && action === 'send') {
       result = await withWebSessionCommandChannel(client, channel =>
         channel.sendMessage(flags.sessionId, {
-          text: flags.text || flags.prompt,
+          text: withStrictCwdPrompt(flags.text || flags.prompt, flags.strictCwd),
           attachmentIds: flags.attachmentIds,
+          mode: flags.mode,
         }),
       );
     } else if (scope === 'web-session' && action === 'approve') {

package/packages/node-sdk/README.md

@@ -1,8 +1,8 @@
-# `@codekanban/sdk`
+# `@codekanban/sdk`
 
-Node SDK and CLI for CodeKanban coding workflows, terminal sessions, and web sessions.
+Node SDK for CodeKanban workflows, terminal sessions, and web sessions.
 
-Use it as a programming-assistant toolkit for launching, observing, and steering CodeKanban work in a registered project or local path, with `web session` as the default structured path and `terminal session` for PTY-style flows.
+Use `@codekanban/sdk` when you want to integrate with CodeKanban from JavaScript. For command-line usage and Codex skill packaging, use `@codekanban/cli`.
 
 ## Features
 
@@ -13,41 +13,26 @@ Use it as a programming-assistant toolkit for launching, observing, and steering
 - Support `standard`, `plan`, and `yolo` Codex profiles
 - Read terminal session lists and AI session summaries
 - Read AI conversations and continue existing terminal sessions
-- Control CodeKanban `web session` runs over HTTP and WebSocket
-- Read `web session` snapshots, history, runtime config, command groups, and archived sessions
-- Send `web session` messages, approvals, user-input answers, model/workflow/permission updates, and move operations
-- Receive normalized `web session` events through `on/off`, `waitFor`, or `for await`
-- Poll a `web session` for a derived actionable state instead of reconstructing history logic yourself
-- Execute the latest plan or answer the active structured prompt with one SDK call
+- Control CodeKanban `web-session` runs over HTTP and WebSocket
+- Read `web-session` snapshots, history, runtime config, command groups, and archived sessions
+- Send `web-session` messages, approvals, user-input answers, model/workflow/permission updates, and move operations
+- Receive normalized `web-session` events through `on/off`, `waitFor`, or `for await`
+- Poll a `web-session` for derived actionable state
+- Wait for a `web-session` to reach a pause/actionable state
+- Run a short web-session loop with automatic user-input answers and latest-plan execution
 
-## CLI
+## Install
 
 ```bash
-node packages/node-sdk/bin/codekanban-sdk.js workflow start --base-url http://127.0.0.1:3000 --path D:\repo --profile plan --add-dir D:\shared --prompt "Inspect and plan the refactor"
-node packages/node-sdk/bin/codekanban-sdk.js session list --base-url http://127.0.0.1:3000 --path D:\repo
-node packages/node-sdk/bin/codekanban-sdk.js session conversation --base-url http://127.0.0.1:3000 --id <db-id>
-node packages/node-sdk/bin/codekanban-sdk.js terminal continue --base-url http://127.0.0.1:3000 --session-id <terminal-session-id> --prompt "Continue from the previous plan"
+npm install @codekanban/sdk
 ```
 
-### Web Session CLI
-
-```bash
-node packages/node-sdk/bin/codekanban-sdk.js web-session create --base-url http://127.0.0.1:3000 --path D:\repo --agent codex --workflow-mode plan --permission-level elevated --title "Planning session"
-node packages/node-sdk/bin/codekanban-sdk.js web-session snapshot --base-url http://127.0.0.1:3000 --project-id <project-id> --session-id <session-id> --limit 80
-node packages/node-sdk/bin/codekanban-sdk.js web-session send --base-url http://127.0.0.1:3000 --session-id <session-id> --text "Continue from the last plan"
-node packages/node-sdk/bin/codekanban-sdk.js web-session approve --base-url http://127.0.0.1:3000 --session-id <session-id>
-node packages/node-sdk/bin/codekanban-sdk.js web-session user-input --base-url http://127.0.0.1:3000 --session-id <session-id> --item-id <item-id> --answers-json '{"scope":["full repo"]}'
-node packages/node-sdk/bin/codekanban-sdk.js web-session watch --base-url http://127.0.0.1:3000 --session-id <session-id> --max-events 20
-```
-
-`web-session watch` writes NDJSON. Add `--raw` to print raw short-key protocol frames.
-
 ## Library
 
 ```js
 import { CodeKanbanClient } from '@codekanban/sdk';
 
-const client = new CodeKanbanClient({ baseURL: 'http://127.0.0.1:3000' });
+const client = new CodeKanbanClient({ baseURL: 'http://127.0.0.1:3007' });
 
 const result = await client.startWorkflow({
   path: 'D:/repo',
@@ -62,7 +47,7 @@ const result = await client.startWorkflow({
 ### Web Session HTTP
 
 ```js
-const client = new CodeKanbanClient({ baseURL: 'http://127.0.0.1:3000' });
+const client = new CodeKanbanClient({ baseURL: 'http://127.0.0.1:3007' });
 
 const session = await client.createWebSession({
   path: 'D:/repo',
@@ -86,10 +71,6 @@ const state = await client.getWebSessionState({
   sessionId: session.id,
 });
 
-if (state.phase === 'running') {
-  return;
-}
-
 if (state.nextAction?.type === 'answer_user_input') {
   await client.answerPendingUserInput({
     projectId: session.projectId,
@@ -129,11 +110,54 @@ const doneState = await client.waitForWebSessionState({
   until: 'done',
   intervalMs: 5000,
   timeoutMs: 120000,
+  settleMs: 2000,
 });
 
 console.log(doneState.lastAssistantMessage?.text);
 ```
 
+### Waiting For Pause States
+
+```js
+const pause = await client.waitForWebSessionPause({
+  projectId: session.projectId,
+  sessionId: session.id,
+  intervalMs: 1500,
+  timeoutMs: 120000,
+  settleMs: 2000,
+});
+
+console.log(pause.reason);
+```
+
+`waitForWebSessionPause()` returns when the session stops making forward progress and needs outside judgment, for example:
+
+- `done`
+- `error`
+- `approval`
+- `user_input`
+- `execute_plan`
+
+### Minimal Web Session Loop
+
+```js
+const result = await client.runWebSessionUntilDone({
+  projectId: session.projectId,
+  sessionId: session.id,
+  intervalMs: 1500,
+  timeoutMs: 120000,
+  settleMs: 2000,
+});
+
+console.log(result.stopReason, result.finalState?.phase);
+```
+
+`runWebSessionUntilDone()` automatically:
+
+- answers ordinary structured user-input prompts with the default `prefer-second-or-text` strategy
+- executes the latest plan when the session reaches an execute-plan pause
+- returns control on `needs_approval`, `needs_user_input`, `needs_execute_plan`, `done`, `error`, `until`, or `timeout`
+
 ### Web Session Command Channel
 
 ```js

package/packages/node-sdk/package.json

@@ -1,18 +1,13 @@
 {
   "name": "@codekanban/sdk",
   "version": "0.1.0",
-  "description": "Node SDK and CLI for launching CodeKanban coding workflows, terminal sessions, and web sessions.",
+  "description": "Node SDK for CodeKanban workflows, terminal sessions, and web sessions.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.js",
-    "./cli": "./src/cli.js"
-  },
-  "bin": {
-    "codekanban-sdk": "./bin/codekanban-sdk.js"
+    ".": "./src/index.js"
   },
   "files": [
-    "bin",
     "src",
     "README.md"
   ],