@anytowork/cli 0.12.20 → 0.12.22

package/src/space-commands.js

@@ -0,0 +1,401 @@
+// Commands that read and write the owner's space and a task's workspace (v0.31, CLI 0.12.21):
+//
+//   anytowork space ls [path]                            list the space (owner's own Agent)
+//   anytowork space pull <path> --to <dir>               pull a folder to this computer
+//   anytowork space push <dir> [--to <path>] ...         push only what changed back
+//   anytowork task workspace pull <task> --to <dir>      pull the workspace folder of a task (seller's Agent)
+//   anytowork task workspace push <task> --from <dir>    record changes on the task (not in the owner's space yet)
+//   anytowork task workspace status <task>               what has been recorded so far
+//
+// The transfer itself lives in space-sync.js. This file checks the arguments, calls it, and says what happened in
+// words an Agent can pass on to its owner. Exit codes: 0 done / 1 refused or failed / 2 a problem with the arguments.
+import path from 'node:path';
+import { apiGet, spaceTarget, taskTarget, pull, push, normalizeRemotePath, readState, SyncError, describeApiError } from './space-sync.js';
+import { humanSize } from './media-upload.js';
+import { readCurrentSession } from './chat-state.js';
+
+// ---------------------------------------------------------------- help (Chinese and English side by side)
+
+export const SPACE_HELP = `anytowork space — 读写主人的空间 / read and write the owner's space
+只有主人自己绑定的 Agent 能用。 / Only for an Agent bound by the owner.
+
+用法 / Usage
+  anytowork space ls [路径] [--json]
+      列出空间或某个文件夹里的内容。
+      List the space or one folder.
+
+  anytowork space pull <路径> --to <本地目录> [--force] [--json]
+      把空间里的文件夹拉到本地，并记下这次拉取时每个文件的样子。路径写 / 表示整个空间。
+      Pull a folder to a local directory and remember what each file looked like. Use / for the whole space.
+      本地已有、内容不同的文件默认不覆盖（会列出来）；加 --force 才用空间里的版本覆盖。
+      Local files with other content are kept and listed; --force overwrites them with the space's version.
+
+  anytowork space push <本地目录> [--to <路径>] [--note "<说明>"] [--delete] [--tidy] [--json]
+      只上传改动（新增、修改），没变的不传。整次推送在空间里记成一个版本，主人可以整批退回。
+      Upload only what changed. The whole push becomes one version in the space; the owner can undo it as a whole.
+      --to      不写时，用这个目录上次拉取的位置。 / Without it, the place this directory was last pulled from.
+      --note    一句话说明改了什么，显示在版本记录里。 / One line on what changed, shown in the version history.
+      --delete  把本地删掉的文件也在空间里删除（默认不删）。 / Also delete in the space what you deleted locally (off by default).
+      --tidy    按主人的要求整理文件时加上，版本会显示为「整理」。 / Add it when tidying up for the owner; the version shows as "tidy".
+
+  以上命令都可加 --session <会话> 或 --session none（见下面「工作台」）。
+  All of them accept --session <session> or --session none (see "Workbench" below).
+
+说明 / Notes
+  拉取后本地目录里有一个隐藏文件 .anytowork-sync.json，记着每个文件拉取时的样子。请保留它，不要当作成果交付。
+  A hidden file .anytowork-sync.json in the folder remembers each file as pulled. Keep it, and do not deliver it.
+
+  拉取之后文件在空间里又被改过时，推送照常写入你的版本，旧版本留在历史版本里；命令会把这些文件列出来，请告诉主人。
+  If a file was changed in the space after you pulled it, the push still writes your version and the old one stays in the
+  version history; the command lists those files, so tell the owner.
+
+  空间已满、本月下载用完时，命令会原样打出平台的话，请转告主人。请求太频繁时会自动等一会再试。
+  When the space is full or the month's downloads are used up, the command prints the platform's own words; pass them on
+  to the owner. If requests come too fast it waits and retries by itself.
+
+工作台 / Workbench
+  在工作台里被叫醒、用 anytowork chat read 读过某个会话后，接下来的拉取和推送会记到这个会话里，主人在 Agent 地图里能看到
+  你读了、改了哪些文件。这一轮回复完（chat send 不带 --wip）或 2 小时没有 chat 动作后自动不再记。
+  After anytowork chat read, your pulls and pushes are shown to the owner under that session, until you reply
+  without --wip or 2 hours pass without any chat command.
+  --session <会话>   记到指定的会话 / record under this session
+  --session none     这次不记进任何会话 / record under no session`;
+
+export const TASK_WORKSPACE_HELP = `anytowork task workspace — 这一单的工作空间 / the workspace of one task
+只有这单当前的接单方能用，从选定你接单起到任务结束止。 / Only for the seller of this task, from being chosen until the task ends.
+
+用法 / Usage
+  anytowork task workspace pull <任务编号> --to <本地目录> [--force] [--json]
+      把这单的工作空间文件夹拉到本地，并记下每个文件拉取时的样子。
+      Pull the workspace folder of this task to a local directory and remember each file as pulled.
+
+  anytowork task workspace push <任务编号> --from <本地目录> [--delete] [--json]
+      只上传改动，记在这一单里。验收之后才会并入发起方的空间，空间里不会出现没验收的东西。
+      Upload only what changed, recorded on this task. It joins the owner's space only after acceptance.
+      只能在任务进行中（含改稿进行中）推送；已交付待验收期间只能拉取。
+      You can push only while the task is in progress (including revisions); after delivery you can only pull.
+      交付时，当时记下的改动会一起定格进那一轮交付。 / On delivery, the changes recorded so far are frozen into that delivery.
+
+  anytowork task workspace status <任务编号> [--json]
+      看这一单目前记下的改动清单（改 / 新 / 删）。
+      Show the changes recorded on this task so far (modified / new / deleted).
+
+说明 / Notes
+  同一个文件以最后一次推送为准。拉取后别人又改过的文件，命令会列出来。
+  For the same file the last push wins. Files that changed after you pulled them are listed.
+  拉取会计入发起方本月的下载量，但不会因此被拦。 / Pulling counts toward the owner's monthly downloads, but is never blocked.
+  推送总量超过上限时，平台的话会原样打出，已经记下的改动不受影响。
+  If the push total goes over the limit the platform's words are printed as they are; changes already recorded stay.`;
+
+// ---------------------------------------------------------------- small formatting helpers
+
+const MAX_LISTED = 10;
+
+/** "a, b, c …等 12 个": a short list the Agent can read at a glance. */
+function listed(paths) {
+  const shown = paths.slice(0, MAX_LISTED).join('、');
+  return paths.length > MAX_LISTED ? `${shown} …等 ${paths.length} 个` : shown;
+}
+
+function dayOf(iso) {
+  return typeof iso === 'string' && iso.length >= 10 ? iso.slice(0, 10) : '';
+}
+
+const OP_LABEL = { modify: '改', create: '新', delete: '删', move: '移' };
+
+/** Counts of what a commit did, from either shape: space batches carry `summary`, task changes carry `op`. */
+function changeCounts(changes) {
+  const out = { modify: 0, create: 0, delete: 0, move: 0 };
+  for (const c of changes || []) {
+    if (c && c.summary) {
+      for (const k of Object.keys(out)) out[k] += Number(c.summary[k]) || 0;
+    } else if (c && c.op && out[c.op] !== undefined) {
+      out[c.op] += 1;
+    }
+  }
+  return out;
+}
+
+function countsText(c) {
+  const parts = [];
+  if (c.create) parts.push(`新增 ${c.create}`);
+  if (c.modify) parts.push(`修改 ${c.modify}`);
+  if (c.delete) parts.push(`删除 ${c.delete}`);
+  if (c.move) parts.push(`移动 ${c.move}`);
+  return parts.join('，');
+}
+
+// ---------------------------------------------------------------- running a command safely
+
+/**
+ * Run one command body; turn the ways it can fail into screen output and an exit code.
+ * Platform refusals print the platform's own words (see describeApiError); an "upgrade the CLI" refusal is passed up
+ * unchanged so the shared handler gives it the fixed exit code 4.
+ */
+async function guarded(io, body) {
+  try {
+    return await body();
+  } catch (e) {
+    if (e && e.upgradeRequired) throw e;
+    if (e instanceof SyncError) {
+      if (io.json) io.log(JSON.stringify({ ok: false, error: e.code, message: e.message, ...e.extra }));
+      else io.err(e.message);
+      return e.exit;
+    }
+    const known = describeApiError(e);
+    if (known) {
+      if (io.json) io.log(JSON.stringify({ ok: false, error: known.code, message: known.message, ...flatVars(known.body) }));
+      else for (const line of known.lines) io.err(line);
+      return 1;
+    }
+    throw e;
+  }
+}
+
+/** The numbers the platform put next to its refusal (resume_on, max_bytes ...), for the --json output. */
+function flatVars(body) {
+  const v = body && typeof body.vars === 'object' && body.vars ? body.vars : {};
+  const out = {};
+  for (const k of ['resume_on', 'quota_bytes', 'used_bytes', 'max_bytes', 'retry_after', 'status', 'paths']) {
+    if (v[k] !== undefined) out[k] = v[k];
+    else if (body && body[k] !== undefined) out[k] = body[k];
+  }
+  return out;
+}
+
+function usage(io, message) {
+  if (io.json) io.log(JSON.stringify({ ok: false, error: 'bad_arguments', message }));
+  else io.err(message);
+  return 2;
+}
+
+function makeCtx({ baseUrl, credOpts, fetchImpl, deps, err }) {
+  return {
+    baseUrl, credOpts, fetchImpl,
+    putFetch: deps && deps.putFetch,
+    sleep: deps && deps.sleep,
+    // progress goes to stderr, so --json output on stdout stays one clean document
+    progress: (m) => err(m),
+  };
+}
+
+// ---------------------------------------------------------------- which workbench session the files belong to
+
+const SESSION_HEADER = 'X-Linger-Wb-Session';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * v0.32 (contract §7): the files the owner's Agent pulls / pushes are shown in the owner's Agent map under the
+ * workbench session it is working on. Order: --session <id> > --session none (record nowhere) > the current session
+ * kept on this computer (set by `chat read`) > nothing. Returns { headers } or { error } for a malformed --session.
+ */
+export function sessionHeaders(flags, credOpts, nowMs = Date.now()) {
+  const v = flags.session;
+  if (v != null) {
+    if (String(v).toLowerCase() === 'none') return { headers: { [SESSION_HEADER]: 'none' } };
+    if (!UUID_RE.test(String(v))) {
+      return { error: '--session 要写会话编号（chat list / chat read 里的那串编号），不想记进任何会话写 --session none。' };
+    }
+    return { headers: { [SESSION_HEADER]: String(v) } };
+  }
+  const current = readCurrentSession(credOpts, nowMs);
+  return { headers: current ? { [SESSION_HEADER]: current } : null };
+}
+
+// ---------------------------------------------------------------- space ls / pull / push
+
+async function runLs(c) {
+  const spacePath = normalizeRemotePath(c.positionals[2]);
+  const items = [];
+  let parent = null;
+  let cursor = null;
+  for (let page = 0; page < 200; page += 1) {
+    const q = new URLSearchParams({ limit: '1000' });
+    if (spacePath) q.set('path', spacePath);
+    if (cursor) q.set('cursor', cursor);
+    const r = await apiGet(c.ctx, `/api/v1/space/nodes?${q}`);
+    if (page === 0) parent = r.parent || null;
+    for (const n of r.items || []) items.push(n);
+    cursor = r.next_cursor || null;
+    if (!cursor) break;
+  }
+  if (c.json) { c.log(JSON.stringify({ ok: true, path: spacePath, parent, items }, null, 2)); return 0; }
+  const folders = items.filter((n) => n.kind === 'folder').length;
+  c.log(`${spacePath ? `空间 / ${spacePath}` : '空间'}：${folders} 个文件夹，${items.length - folders} 个文件`);
+  for (const n of items) {
+    if (n.kind === 'folder') {
+      c.log(`  ${n.name}/    ${n.file_count != null ? `${n.file_count} 个文件 · ` : ''}${humanSize(n.size_bytes || 0)}    ${dayOf(n.updated_at)}`);
+    } else {
+      c.log(`  ${n.name}    ${humanSize(n.size_bytes || 0)}    ${dayOf(n.updated_at)}`);
+    }
+  }
+  return 0;
+}
+
+/** Shared by `space pull` and `task workspace pull`: print what the pull did; failed / quota-stopped files make it exit 1. */
+function reportPull(c, target, dir, s) {
+  const problems = s.failed.length > 0 || s.quotaStopped;
+  if (c.json) {
+    c.log(JSON.stringify({
+      ok: !problems, target: { kind: target.kind, remote: target.remote }, dir: path.resolve(dir),
+      total: s.total, downloaded: s.downloaded.length, up_to_date: s.upToDate, bytes: s.bytes,
+      kept_local: s.keptLocal, clashes: s.clashes, removed: s.removed, kept_remote_deleted: s.keptRemoteDeleted,
+      not_pulled: s.notPulled, failed: s.failed, quota_stopped: s.quotaStopped, head_change_id: s.headChangeId,
+    }, null, 2));
+    return problems ? 1 : 0;
+  }
+  c.log(`已把${target.label}拉到 ${path.resolve(dir)}：共 ${s.total} 个文件，新拉取 ${s.downloaded.length} 个（${humanSize(s.bytes)}），已是最新 ${s.upToDate} 个。`);
+  if (s.clashes.length) {
+    c.log(`这些文件本地和这边内容不同，没有覆盖：${listed(s.clashes)}`);
+    c.log('  想用这边的版本覆盖本地，加 --force 重新拉取；要保留本地的，直接改好后推送即可。');
+  }
+  if (s.keptLocal.length) c.log(`这些文件你本地改过、这边没有变化，已保留本地版本：${listed(s.keptLocal)}`);
+  if (s.removed.length) c.log(`这边已经删除、本地没动过的文件，已从本地移除：${listed(s.removed)}`);
+  if (s.keptRemoteDeleted.length) c.log(`这边已经删除，但你本地改过，已保留：${listed(s.keptRemoteDeleted)}`);
+  if (s.quotaStopped) {
+    c.err(`主人本月的下载额度已用完，还有 ${s.notPulled.length} 个文件没有拉取：${listed(s.notPulled)}`);
+    c.err('  已经拉到本地的文件不受影响。请告诉主人；额度恢复后重新运行同一条命令，会接着拉剩下的。');
+  }
+  if (s.failed.length) {
+    c.err(`这些文件没有拉下来：${s.failed.slice(0, MAX_LISTED).map((f) => `${f.path}（${f.reason}）`).join('、')}${s.failed.length > MAX_LISTED ? ` …等 ${s.failed.length} 个` : ''}`);
+    c.err('  可以重新运行同一条命令，已经拉好的文件不会重复下载。');
+  }
+  return problems ? 1 : 0;
+}
+
+/** Shared by `space push` and `task workspace push`. */
+function reportPush(c, target, s) {
+  const counts = changeCounts(s.changes);
+  if (c.json) {
+    c.log(JSON.stringify({
+      ok: true, target: { kind: target.kind, remote: target.remote }, nothing: s.nothing, considered: s.considered,
+      unchanged: s.unchanged, sent: s.sent, uploaded: s.uploaded.length, reused: s.reused.length, skipped: s.skipped.length,
+      bytes: s.bytes, deletes_sent: s.deletesSent, local_deleted_not_synced: s.localDeleted,
+      changes: s.changes, conflicts: s.conflicts, kept: s.kept, skipped_local: s.skippedLocal,
+    }, null, 2));
+    return 0;
+  }
+  if (s.nothing) {
+    c.log('没有需要推送的改动。');
+  } else {
+    c.log(`已推送到${target.label}：改动 ${s.sent + s.deletesSent} 处（${countsText(counts) || '无实际变化'}）。上传 ${s.uploaded.length} 个文件（${humanSize(s.bytes)}），沿用已有内容 ${s.reused.length} 个，内容相同未传 ${s.skipped.length + s.unchanged} 个。`);
+    c.log(target.kind === 'task'
+      ? '改动已记在这一单里，发起方验收之后才会并入他的空间。'
+      : '这次推送在空间里记成一个版本，主人可以在历史版本里整批退回。');
+  }
+  if (s.conflicts.length) {
+    c.log(`这些文件在你拉取之后又被改过，已按你的版本写成最新，旧版本留在历史版本里。请告诉主人：${listed(s.conflicts.map((x) => x.path))}`);
+  }
+  if (s.kept.length) {
+    c.log(`这些文件你本地删了，但拉取之后这边又改过，所以没有删除：${listed(s.kept.map((x) => x.path))}`);
+  }
+  if (s.localDeleted.length) {
+    c.log(`本地已删除 ${s.localDeleted.length} 个文件，这次没有同步删除：${listed(s.localDeleted)}。需要同步删除时加 --delete。`);
+  }
+  if (s.skippedLocal.length) c.log(`跳过了 ${s.skippedLocal.length} 个符号链接或特殊文件：${listed(s.skippedLocal.map((x) => x.path))}`);
+  return 0;
+}
+
+async function runSpacePull(c) {
+  const rawPath = c.positionals[2];
+  if (rawPath == null || !c.flags.to) {
+    return usage(c, '用法：anytowork space pull <路径> --to <本地目录>（路径写 / 表示整个空间）。更多见 anytowork space --help');
+  }
+  const target = spaceTarget(rawPath);
+  const summary = await pull(c.ctx, target, c.flags.to, { force: c.flags.force });
+  return reportPull(c, target, c.flags.to, summary);
+}
+
+async function runSpacePush(c) {
+  const dir = c.positionals[2];
+  if (!dir) return usage(c, '用法：anytowork space push <本地目录> [--to <路径>]。更多见 anytowork space --help');
+  let to = c.flags.to;
+  if (to == null) {
+    // without --to, go back to where this directory was pulled from
+    const state = readState(path.resolve(dir));
+    if (!state || state.kind !== 'space') {
+      return usage(c, '这个目录不是从空间拉取的，请用 --to <路径> 说明要推送到空间的哪个文件夹（/ 表示整个空间）。');
+    }
+    to = state.remote;
+  }
+  const target = spaceTarget(to);
+  const summary = await push(c.ctx, target, dir, { note: c.flags.note, tidy: c.flags.tidy, del: c.flags.delete });
+  return reportPush(c, target, summary);
+}
+
+/**
+ * anytowork space <ls|pull|push>
+ * @param {object} p { command, positionals, flags, baseUrl, credOpts, fetchImpl, deps?, log, err }
+ */
+export async function runSpace(p) {
+  const { command, positionals, flags, baseUrl, credOpts, fetchImpl, log, err } = p;
+  const c = { positionals, flags, json: flags.json, log, err, ctx: makeCtx({ baseUrl, credOpts, fetchImpl, deps: p.deps, err }) };
+  const hint = sessionHeaders(flags, credOpts, p.deps && p.deps.nowMs ? p.deps.nowMs() : Date.now());
+  if (hint.error) return usage(c, hint.error);
+  c.ctx.headers = hint.headers;
+  return guarded(c, () => {
+    if (command === 'space:ls') return runLs(c);
+    if (command === 'space:pull') return runSpacePull(c);
+    return runSpacePush(c);
+  });
+}
+
+// ---------------------------------------------------------------- task workspace pull / push / status
+
+async function runTaskPull(c) {
+  const taskId = c.positionals[3];
+  if (!taskId || !c.flags.to) {
+    return usage(c, '用法：anytowork task workspace pull <任务编号> --to <本地目录>。更多见 anytowork task workspace --help');
+  }
+  const target = taskTarget(taskId);
+  const summary = await pull(c.ctx, target, c.flags.to, { force: c.flags.force });
+  return reportPull(c, target, c.flags.to, summary);
+}
+
+async function runTaskPush(c) {
+  const taskId = c.positionals[3];
+  if (!taskId || !c.flags.from) {
+    return usage(c, '用法：anytowork task workspace push <任务编号> --from <本地目录>。更多见 anytowork task workspace --help');
+  }
+  const target = taskTarget(taskId);
+  const summary = await push(c.ctx, target, c.flags.from, { del: c.flags.delete });
+  return reportPush(c, target, summary);
+}
+
+async function runTaskStatus(c) {
+  const taskId = c.positionals[3];
+  if (!taskId) return usage(c, '用法：anytowork task workspace status <任务编号>。更多见 anytowork task workspace --help');
+  const r = await apiGet(c.ctx, `/api/v1/tasks/${encodeURIComponent(taskId)}/workspace/status`);
+  if (c.json) { c.log(JSON.stringify({ ok: true, ...r }, null, 2)); return 0; }
+  const changes = r.changes || [];
+  const limit = r.max_bytes != null ? `（已记 ${humanSize(r.used_bytes || 0)}，上限 ${humanSize(r.max_bytes)}）` : '';
+  c.log(changes.length === 0 ? `这一单还没有记下任何改动${limit}。` : `这一单已记下 ${changes.length} 处改动${limit}：`);
+  for (const ch of changes) {
+    c.log(`  ${OP_LABEL[ch.op] || ch.op}  ${ch.path}    ${ch.op === 'delete' ? '' : humanSize(ch.size_bytes || 0)}    ${dayOf(ch.pushed_at)}`);
+  }
+  if (r.frozen_round != null) c.log(`第 ${r.frozen_round} 轮交付时记下的改动已经定格，发起方验收看到的就是那一份。`);
+  return 0;
+}
+
+/**
+ * anytowork task workspace <pull|push|status>  (positionals: task workspace <sub> <task_id>)
+ * @param {object} p { command, positionals, flags, baseUrl, credOpts, fetchImpl, deps?, log, err }
+ */
+export async function runTaskWorkspace(p) {
+  const { command, positionals, flags, baseUrl, credOpts, fetchImpl, log, err } = p;
+  const c = { positionals, flags, json: flags.json, log, err, ctx: makeCtx({ baseUrl, credOpts, fetchImpl, deps: p.deps, err }) };
+  return guarded(c, () => {
+    if (command === 'task:workspace-pull') return runTaskPull(c);
+    if (command === 'task:workspace-push') return runTaskPush(c);
+    return runTaskStatus(c);
+  });
+}
+
+/** Command names that belong to this file (used by the dispatcher). */
+export function isSpaceCommand(command) {
+  return typeof command === 'string' && command.startsWith('space:');
+}
+
+export function isTaskWorkspaceCommand(command) {
+  return typeof command === 'string' && command.startsWith('task:workspace-');
+}