@commonlyai/cli 0.1.214 → 0.1.215

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.214",
+  "version": "0.1.215",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/task.js

@@ -0,0 +1,278 @@
+/**
+ * commonly task <subcommand>
+ *
+ * list   — the pod's board, optionally narrowed by status, or to rows this identity holds
+ * create — a new row; --notes is a second request, because create does not take notes
+ * claim  — take the lease on a row
+ * update — change a row's fields, and/or append a history note
+ * close  — mark a row done, as its creator or its holder
+ *
+ * Identity and base URL come from ../lib/task.js. Every subcommand goes through
+ * connect() below, so none can grow its own fallback to the saved login. Flags are
+ * checked before the first request, so a refusal costs no network round trip.
+ */
+
+import { TOKEN_FILE_ENV } from '../lib/inbox.js';
+import {
+  TASK_PRIORITIES,
+  TASK_STATUSES,
+  TASK_TOKEN_ENV,
+  TaskRefusal,
+  UPDATE_STATUSES,
+  checkPriority,
+  checkStatusFilter,
+  checkTaskId,
+  checkUpdateStatus,
+  createTaskClient,
+  describeFailure,
+  formatTaskLine,
+  requireText,
+  resolveTaskBaseUrl,
+  resolveTaskToken,
+  taskPath,
+} from '../lib/task.js';
+
+export const TASK_TOKEN_HELP = `Agent token file (or ${TOKEN_FILE_ENV}, or ${TASK_TOKEN_ENV})`;
+
+const connect = (opts, env, fetchImpl) => createTaskClient({
+  baseUrl: resolveTaskBaseUrl(opts, env),
+  token: resolveTaskToken(opts, env),
+  fetchImpl,
+});
+
+const podOf = (opts) => requireText(opts.pod, '--pod');
+
+const report = (err, error) => {
+  error(err instanceof TaskRefusal ? `refusing: ${err.message}` : describeFailure(err));
+  return 1;
+};
+
+// A row goes out as JSON for agents, and as the line a person scans otherwise.
+const emitRow = (opts, log, task) => {
+  log(opts.json ? JSON.stringify(task, null, 2) : formatTaskLine(task));
+};
+
+export const runTaskList = async (opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const status = opts.status === undefined ? undefined : checkStatusFilter(opts.status);
+    const { tasks } = await connect(opts, env, fetchImpl).get(taskPath(pod), { status });
+    // The server marks each row claimedByMe for this identity, so --mine needs no second request.
+    const rows = opts.mine ? tasks.filter((task) => task.claimedByMe) : tasks;
+    if (opts.json) {
+      log(JSON.stringify(rows, null, 2));
+    } else if (rows.length === 0) {
+      log('(no tasks match)');
+    } else {
+      for (const task of rows) log(formatTaskLine(task));
+    }
+    return 0;
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const runTaskCreate = async (opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const body = { title: requireText(opts.title, '--title') };
+    if (opts.priority !== undefined) body.priority = checkPriority(opts.priority);
+    if (opts.assignee !== undefined) body.assignee = requireText(opts.assignee, '--assignee');
+    if (opts.dep !== undefined) body.dep = checkTaskId(opts.dep);
+    const notes = opts.notes === undefined ? undefined : requireText(opts.notes, '--notes');
+    const client = connect(opts, env, fetchImpl);
+    const { task } = await client.post(taskPath(pod), body);
+    if (notes === undefined) {
+      emitRow(opts, log, task);
+      return 0;
+    }
+    // The row exists once the create returns. If the notes fail, say so, so nobody
+    // retries the create and makes a twin.
+    try {
+      const { task: noted } = await client.patch(taskPath(pod, task.taskId), { notes });
+      emitRow(opts, log, noted);
+      return 0;
+    } catch (err) {
+      error(`Created ${task.taskId}, but --notes did not save. ${describeFailure(err)}`);
+      return 1;
+    }
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const runTaskClaim = async (taskArg, opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const taskId = checkTaskId(taskArg);
+    const body = opts.continueAnyway ? { continueAnyway: true } : {};
+    const { task } = await connect(opts, env, fetchImpl).post(`${taskPath(pod, taskId)}/claim`, body);
+    emitRow(opts, log, task);
+    return 0;
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const runTaskUpdate = async (taskArg, opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const taskId = checkTaskId(taskArg);
+    const fields = {};
+    if (opts.status !== undefined) fields.status = checkUpdateStatus(opts.status);
+    // An empty value unassigns. The server stores that as null, not as '', so the row
+    // reads as unassigned to the router.
+    if (opts.assignee !== undefined) fields.assignee = String(opts.assignee).trim();
+    if (opts.title !== undefined) fields.title = requireText(opts.title, '--title');
+    if (opts.priority !== undefined) fields.priority = checkPriority(opts.priority);
+    // "none" clears the dependency. Sending '' would store a dependency that names nothing.
+    if (opts.dep !== undefined) fields.dep = opts.dep === 'none' ? null : checkTaskId(opts.dep);
+    const note = opts.note === undefined ? undefined : requireText(opts.note, '--note');
+    if (Object.keys(fields).length === 0 && note === undefined) {
+      throw new TaskRefusal('nothing to change. Pass --status, --assignee, --title, --priority, --dep or --note.');
+    }
+    const client = connect(opts, env, fetchImpl);
+    const path = taskPath(pod, taskId);
+    let task = null;
+    if (Object.keys(fields).length > 0) ({ task } = await client.patch(path, fields));
+    if (note !== undefined) {
+      try {
+        const body = opts.continueAnyway ? { text: note, continueAnyway: true } : { text: note };
+        ({ task } = await client.post(`${path}/updates`, body));
+      } catch (err) {
+        // With no field change before it, a failed note is the whole failure.
+        if (task === null) throw err;
+        error(`Updated ${taskId}, but --note did not post. ${describeFailure(err)}`);
+        return 1;
+      }
+    }
+    emitRow(opts, log, task);
+    return 0;
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const runTaskClose = async (taskArg, opts = {}, deps = {}) => {
+  const {
+    env = process.env, fetchImpl = fetch, log = console.log, error = console.error,
+  } = deps;
+  try {
+    const pod = podOf(opts);
+    const taskId = checkTaskId(taskArg);
+    const prUrl = opts.pr === undefined ? undefined : requireText(opts.pr, '--pr');
+    // No notes key here. /complete replaces the row's notes whenever one is sent.
+    const body = prUrl === undefined ? {} : { prUrl };
+    const { task } = await connect(opts, env, fetchImpl).post(`${taskPath(pod, taskId)}/complete`, body);
+    emitRow(opts, log, task);
+    return 0;
+  } catch (err) {
+    return report(err, error);
+  }
+};
+
+export const registerTask = (program) => {
+  const task = program
+    .command('task')
+    .description('Read and write the task board as an agent (list, create, claim, update, close)');
+
+  task.addHelpText('after', `
+The board is read and written as the identity in a token file, and nowhere else:
+
+  $ commonly task list --pod <podId> --token-file <path>
+  $ COMMONLY_AGENT_TOKEN=<token> commonly task claim TASK-123 --pod <podId>
+
+The identity is --token-file, then COMMONLY_TOKEN_FILE, then COMMONLY_AGENT_TOKEN.
+The saved login and COMMONLY_TOKEN are never read: a write made under an
+operator's login lands on the row under that operator's name.
+
+Each verb does what it says. \`claim\` takes the lease. \`close\` stamps the
+completion time and the PR. \`update --status\` sets only pending or blocked, so it
+cannot claim or close a row. \`update --note\` appends a history line. The row's
+notes are set by \`create --notes\` and are not editable here.
+
+A claim or a note can refuse with unseen messages in the pod. Read them and retry,
+or pass --continue-anyway to go ahead without reading them.
+
+Examples:
+  $ commonly task list --pod <podId> --status pending,claimed
+  $ commonly task list --pod <podId> --mine --json
+  $ commonly task create --pod <podId> --title "Fix the board" --priority P1 --notes "Repro in staging"
+  $ commonly task claim TASK-123 --pod <podId>
+  $ commonly task update TASK-123 --pod <podId> --note "PR is up"
+  $ commonly task close TASK-123 --pod <podId> --pr https://github.com/Team-Commonly/commonly/pull/<n>
+`);
+
+  task
+    .command('list')
+    .description("List a pod's task board")
+    .requiredOption('--pod <podId>', 'Pod whose board to read')
+    .option('--status <list>', `Only these statuses, comma-separated (${TASK_STATUSES.join('|')})`)
+    .option('--mine', 'Only rows this identity holds a claim on')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the rows as JSON')
+    .action(async (opts) => { process.exit(await runTaskList(opts)); });
+
+  task
+    .command('create')
+    .description('Create a row, then set its --notes (create does not take notes)')
+    .requiredOption('--pod <podId>', 'Pod to create the row in')
+    .requiredOption('--title <text>', 'Row title')
+    .option('--notes <text>', 'Notes to set once the row exists')
+    .option('--priority <P>', `${TASK_PRIORITIES.join('|')} (default P2)`)
+    .option('--assignee <name>', 'Assign the row at creation')
+    .option('--dep <TASK-n>', 'Row this one waits on')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the row as JSON')
+    .action(async (opts) => { process.exit(await runTaskCreate(opts)); });
+
+  task
+    .command('claim <taskId>')
+    .description('Take the lease on a row (TASK-n)')
+    .requiredOption('--pod <podId>', 'Pod the row is in')
+    .option('--continue-anyway', 'Claim even with unseen messages in the pod')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the row as JSON')
+    .action(async (taskId, opts) => { process.exit(await runTaskClaim(taskId, opts)); });
+
+  task
+    .command('update <taskId>')
+    .description("Change a row's fields, and/or append a history note")
+    .requiredOption('--pod <podId>', 'Pod the row is in')
+    .option('--status <status>', `${UPDATE_STATUSES.join('|')} (claim and close have their own commands)`)
+    .option('--assignee <name>', 'Reassign the row; an empty value unassigns it')
+    .option('--title <text>', 'New title')
+    .option('--priority <P>', TASK_PRIORITIES.join('|'))
+    .option('--dep <TASK-n>', 'Row this one waits on; "none" clears it')
+    .option('--note <text>', 'Append a history note')
+    .option('--continue-anyway', 'Post the note even with unseen messages in the pod')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the row as JSON')
+    .action(async (taskId, opts) => { process.exit(await runTaskUpdate(taskId, opts)); });
+
+  task
+    .command('close <taskId>')
+    .description('Mark a row done, as its creator or its holder')
+    .requiredOption('--pod <podId>', 'Pod the row is in')
+    .option('--pr <url>', 'Pull request that delivered the row')
+    .option('--token-file <path>', TASK_TOKEN_HELP)
+    .option('--instance <url>', 'Target Commonly instance')
+    .option('--json', 'Emit the row as JSON')
+    .action(async (taskId, opts) => { process.exit(await runTaskClose(taskId, opts)); });
+};

package/src/index.js

@@ -23,6 +23,7 @@ import { registerDev } from './commands/dev.js';
 import { registerVerify } from './commands/verify.js';
 import { registerDoctor } from './commands/doctor.js';
 import { registerMcp } from './commands/mcp.js';
+import { registerTask } from './commands/task.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
@@ -60,6 +61,9 @@ registerVerify(program);
 registerDoctor(program);
 registerMcp(program);
 
+// The task board as an agent: list, create, claim, update, close (TASK-703)
+registerTask(program);
+
 // Each subcommand owns its own `--instance <url>` flag; a program-level
 // duplicate shadowed the subcommand value on commander v12, causing
 // `commonly login --instance …` to silently fall back to the default URL.

package/src/lib/task.js

@@ -0,0 +1,234 @@
+/**
+ * The task board from the CLI: identity, the request layer, and one-line
+ * rendering. The routes are the ones the commonly_* task tools call
+ * (backend/routes/tasksApi.ts), so the CLI and the MCP cannot disagree about
+ * what a write means.
+ *
+ * Identity is an explicit token and nothing else: --token-file, then
+ * COMMONLY_TOKEN_FILE, then COMMONLY_AGENT_TOKEN. The saved login and
+ * COMMONLY_TOKEN are never read. A write made under an operator's saved login
+ * lands on the row under that operator's name.
+ */
+
+import { readFileSync } from 'fs';
+import { DEFAULT_URL, resolveInstance } from './config.js';
+import { extractToken, resolveTokenFilePath, TOKEN_FILE_ENV } from './inbox.js';
+
+export const API_URL_ENV = 'COMMONLY_API_URL';
+export const TASK_TOKEN_ENV = 'COMMONLY_AGENT_TOKEN';
+export const TASK_STATUSES = ['pending', 'claimed', 'done', 'blocked'];
+// `update` writes only these. A claim writes the lease, which /claim owns, and a
+// close stamps completedAt and the PR, which PATCH does not.
+export const UPDATE_STATUSES = ['pending', 'blocked'];
+export const TASK_PRIORITIES = ['P0', 'P1', 'P2', 'P3'];
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/** A refusal made before any request: a bad flag, or no identity to send. */
+export class TaskRefusal extends Error {}
+
+/** A failed call. `status` is 0 when the server was never reached. */
+export class TaskRequestError extends Error {
+  constructor(message, { status = 0, code = null, body = null } = {}) {
+    super(message);
+    this.name = 'TaskRequestError';
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+}
+
+export const requireText = (value, flag) => {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text) throw new TaskRefusal(`${flag} needs a value.`);
+  return text;
+};
+
+export const checkPriority = (value) => {
+  const priority = String(value).trim().toUpperCase();
+  if (!TASK_PRIORITIES.includes(priority)) {
+    throw new TaskRefusal(`--priority must be ${TASK_PRIORITIES.join(', ')} (got '${value}').`);
+  }
+  return priority;
+};
+
+export const checkStatusFilter = (value) => {
+  const statuses = String(value).split(',').map((s) => s.trim()).filter(Boolean);
+  if (statuses.length === 0 || statuses.some((s) => !TASK_STATUSES.includes(s))) {
+    throw new TaskRefusal(`--status takes ${TASK_STATUSES.join(', ')}, comma-separated (got '${value}').`);
+  }
+  return statuses.join(',');
+};
+
+export const checkUpdateStatus = (value) => {
+  const status = String(value).trim().toLowerCase();
+  if (status === 'claimed') {
+    throw new TaskRefusal('--status claimed is refused: `commonly task claim` writes the lease, and a bare status does not.');
+  }
+  if (status === 'done') {
+    throw new TaskRefusal('--status done is refused: `commonly task close` stamps completedAt and the PR, and PATCH does not.');
+  }
+  if (!UPDATE_STATUSES.includes(status)) {
+    throw new TaskRefusal(`--status must be ${UPDATE_STATUSES.join(' or ')} (got '${value}').`);
+  }
+  return status;
+};
+
+/** TASK-669, task-669 and 669 name one row. Anything else is refused before a request. */
+export const checkTaskId = (value) => {
+  const match = String(value ?? '').trim().match(/^(?:task-)?(\d+)$/i);
+  if (!match) throw new TaskRefusal(`task id must look like TASK-123 (got '${value ?? ''}').`);
+  return `TASK-${String(Number(match[1])).padStart(3, '0')}`;
+};
+
+/**
+ * Resolve the token. A token file that exists but holds nothing is refused by
+ * its path. The message never suggests `commonly login`, because pointing back
+ * at the saved login is the thing this rule exists to prevent.
+ */
+export const resolveTaskToken = (opts = {}, env = process.env) => {
+  const tokenFile = resolveTokenFilePath(opts, env);
+  if (tokenFile) {
+    let raw;
+    try {
+      raw = readFileSync(tokenFile, 'utf8');
+    } catch (err) {
+      throw new TaskRefusal(`cannot read the token file ${tokenFile} (${err?.code || err?.message}).`);
+    }
+    const token = extractToken(raw);
+    if (!token) throw new TaskRefusal(`no token in ${tokenFile}. Expected a raw token, or JSON with a token field.`);
+    return token;
+  }
+  const fromEnv = extractToken(env[TASK_TOKEN_ENV]);
+  if (fromEnv) return fromEnv;
+  throw new TaskRefusal(`no token. Pass --token-file <path>, or set ${TOKEN_FILE_ENV} or ${TASK_TOKEN_ENV}.`);
+};
+
+/**
+ * --instance takes a URL or a saved key, and an unknown key is refused. Falling
+ * back to the default host would send this token to an instance it was not
+ * minted on.
+ */
+export const resolveTaskBaseUrl = (opts = {}, env = process.env) => {
+  if (opts.instance) {
+    const inst = resolveInstance(opts.instance);
+    if (!inst?.url) {
+      throw new TaskRefusal(`unknown instance '${opts.instance}'. Pass its URL, or a saved instance key.`);
+    }
+    return inst.url.replace(/\/$/, '');
+  }
+  const fromEnv = String(env[API_URL_ENV] || '').trim().replace(/\/$/, '');
+  return fromEnv || DEFAULT_URL;
+};
+
+/** `/api/v1/tasks/<pod>` for the board, and `…/<taskId>` for one row. */
+export const taskPath = (podId, taskId = null) => [
+  '/api/v1/tasks',
+  encodeURIComponent(podId),
+  ...(taskId === null ? [] : [encodeURIComponent(taskId)]),
+].join('/');
+
+const messageFor = (status, body, text) => {
+  if (body && typeof body.error === 'string' && body.error) return body.error;
+  if (body && typeof body.message === 'string' && body.message) return body.message;
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return `HTTP ${status}`;
+  if (/^<(?:!doctype|html)/i.test(trimmed)) {
+    const title = trimmed.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1];
+    return title ? title.replace(/\s+/g, ' ').trim() : 'HTML error page';
+  }
+  return trimmed.replace(/\s+/g, ' ').slice(0, 200);
+};
+
+/**
+ * One attempt per call. The writes here are POSTs, and a retried create or note
+ * lands twice, so a failure is reported and the caller decides what to do next.
+ */
+export const createTaskClient = ({ baseUrl, token, fetchImpl = fetch }) => {
+  const send = async (method, path, body) => {
+    let res;
+    try {
+      res = await fetchImpl(`${baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+    } catch (err) {
+      throw new TaskRequestError(`could not reach ${baseUrl} (${err?.message || err}).`);
+    }
+    const text = await res.text();
+    let parsed = null;
+    try {
+      parsed = text ? JSON.parse(text) : null;
+    } catch {
+      parsed = null;
+    }
+    if (!res.ok) {
+      throw new TaskRequestError(messageFor(res.status, parsed, text), {
+        status: res.status,
+        code: parsed?.code || null,
+        body: parsed,
+      });
+    }
+    return parsed;
+  };
+
+  const get = (path, params = {}) => {
+    const query = new URLSearchParams(
+      Object.entries(params).filter(([, value]) => value !== undefined && value !== ''),
+    ).toString();
+    return send('GET', query ? `${path}?${query}` : path);
+  };
+
+  return {
+    get,
+    post: (path, body = {}) => send('POST', path, body),
+    patch: (path, body = {}) => send('PATCH', path, body),
+  };
+};
+
+const clockOf = (iso) => {
+  if (!iso) return null;
+  const at = new Date(iso);
+  return Number.isNaN(at.getTime()) ? null : `${at.toISOString().slice(11, 16)}Z`;
+};
+
+/** One row, as a human reads it. A claimed row also says whether its lease holds. */
+export const formatTaskLine = (task) => {
+  const line = [task.taskId, task.status, task.priority || '-', task.assignee || '-', task.title].join('  ');
+  if (task.status !== 'claimed') return line;
+  const at = clockOf(task.claimExpiresAt);
+  if (!at) return line;
+  const lapsed = new Date(task.claimExpiresAt).getTime() < Date.now();
+  return `${line} (${lapsed ? 'lease lapsed' : 'held until'} ${at})`;
+};
+
+/**
+ * One line for a failed call. The unseen-messages hold and a lease conflict get
+ * their own wording, because a seat acts on each differently. Everything else is
+ * the server's own text.
+ */
+export const describeFailure = (err) => {
+  if (!(err instanceof TaskRequestError)) return `Failed: ${err?.message || err}`;
+  if (err.status === 0) return `Failed: ${err.message}`;
+  const body = err.body || {};
+  let line;
+  if (err.code === 'unseen_messages') {
+    const count = Number(body.unseenCount) || 0;
+    line = `Failed (HTTP ${err.status}): ${count} unseen message${count === 1 ? '' : 's'} in this pod. `
+      + 'Read them and retry, or pass --continue-anyway to go ahead.';
+  } else {
+    const detail = [
+      body.claimedBy ? `held by ${body.claimedBy}` : null,
+      clockOf(body.claimExpiresAt) ? `lease until ${clockOf(body.claimExpiresAt)}` : null,
+    ].filter(Boolean).join(', ');
+    line = `Failed (HTTP ${err.status}): ${err.message}${detail ? ` (${detail})` : ''}`;
+    if (err.status === 401) {
+      line += '. Check the agent token: --token-file, COMMONLY_TOKEN_FILE or COMMONLY_AGENT_TOKEN.';
+    }
+  }
+  return line.replace(/\s+/g, ' ');
+};