neodrop-cli 1.1.0 → 2.0.0

package/lib/api.mjs

@@ -1,22 +1,25 @@
-// tRPC 11 HTTP 调用最小封装（适配 backend 配置的 superjson transformer）。
+// Minimal tRPC 11 HTTP client (matches the backend's superjson transformer).
 //
-// URL 形态：
+// URL shapes:
 //   - query:    GET  /trpc/<proc>?input=<urlencoded {json:<input>}>
 //   - mutation: POST /trpc/<proc>  body = {json:<input>}
 //
-// 响应形态（superjson）：
-//   - 成功：{ result: { data: { json: <T>, meta?: {...} } } }
-//   - 失败：{ error: { json: { message, code, data: {...} } } }
+// Response shapes (superjson):
+//   - success: { result: { data: { json: <T>, meta?: {...} } } }
+//   - failure: { error: { json: { message, code, data: {...} } } }
 //
-// 入参 / 出参的 superjson `meta` 字段用于 Date 等非 JSON 类型还原，CLI 用不上
-// （凭证 expiresAt 直接用 ISO 字符串），这里只取 `json` 字段。
+// The superjson `meta` field on inputs/outputs restores non-JSON types such as
+// Date, which the CLI doesn't need (credential expiresAt is a plain ISO string),
+// so we only read the `json` field here.
 //
-// 零运行时依赖：用 Node 原生 fetch（Node 18+），不引第三方 HTTP 库。
+// Zero runtime dependencies: uses Node's native fetch (Node 18+), no third-party
+// HTTP library.
 
 export class ApiError extends Error {
-  // tRPC 业务错误（HTTP >= 400 或 body.error 非空）。
-  // code 来自 tRPC 的错误码（'UNAUTHORIZED' / 'NOT_FOUND' / 'BAD_REQUEST' 等），
-  // CLI 上层可据此分流（如 401 提示重 login）。
+  // tRPC business error (HTTP >= 400 or a non-empty body.error).
+  // code comes from tRPC's error codes ('UNAUTHORIZED' / 'NOT_FOUND' /
+  // 'BAD_REQUEST', etc.), so the CLI can branch on it (e.g. prompt to re-login
+  // on 401).
   constructor(message, code = "", httpStatus = 0) {
     super(code ? `[${code}] ${message}` : message);
     this.name = "ApiError";
@@ -28,14 +31,15 @@ export class ApiError extends Error {
 function buildUrl(apiOrigin, proc, inputValue) {
   const base = `${apiOrigin.replace(/\/+$/, "")}/trpc/${proc}`;
   if (inputValue === undefined) return base;
-  // superjson 入参 wrapper：{ json: <value> }
+  // superjson input wrapper: { json: <value> }
   const qs = new URLSearchParams({ input: JSON.stringify({ json: inputValue }) });
   return `${base}?${qs.toString()}`;
 }
 
-// Cloudflare WAF 看到默认 UA 会按 bot 拒（HTTP 403 + error code 1010）。给一个
-// 老实的客户端身份——告诉 CF/origin「这是 neodrop-cli」，便于排查与白名单。
-// 改 UA 不是为了伪装，是为了通过基础的 client fingerprint check。
+// Cloudflare WAF rejects the default UA as a bot (HTTP 403 + error code 1010).
+// Present an honest client identity — telling CF/origin "this is neodrop-cli"
+// makes debugging and allowlisting easier. Setting the UA is not about
+// disguise, it's about passing the basic client fingerprint check.
 const USER_AGENT = "neodrop-cli/1.0 (+https://github.com/NeoDropAI/neodrop-skills)";
 
 async function doRequest({ method, url, token, body }) {
@@ -46,11 +50,13 @@ async function doRequest({ method, url, token, body }) {
   };
   if (token) headers.authorization = `Bearer ${token}`;
 
-  // 一次 transparent retry——线上 Cloudflare/upstream 偶发 TLS-layer 抖动
-  // （"EOF occurred in violation of protocol" 等）。mutation 也加 retry：tRPC
-  // mutation 在网络抖动 + 业务层未提交时是幂等可重的（最多多签发一个 PAT/订阅，
-  // 可接受代价）。注意 fetch 对 4xx/5xx 不抛错——那由 handleResponse 处理，
-  // 这里只 retry 真正的网络层异常。
+  // One transparent retry — production Cloudflare/upstream occasionally has
+  // TLS-layer hiccups ("EOF occurred in violation of protocol", etc.). Retry is
+  // applied to mutations too: a tRPC mutation is idempotent-enough to retry when
+  // the network flaked before the business layer committed (worst case, one
+  // extra PAT/subscription is issued — an acceptable cost). Note that fetch does
+  // not throw on 4xx/5xx — that's handled by handleResponse; here we only retry
+  // true network-layer failures.
   let lastErr;
   for (let i = 0; i < 2; i++) {
     try {
@@ -59,11 +65,12 @@ async function doRequest({ method, url, token, body }) {
       lastErr = err;
     }
   }
-  // Node fetch 把真正的原因藏在 err.cause（如 ECONNREFUSED / ENOTFOUND /
-  // self-signed certificate）；err.message 通常只是笼统的 "fetch failed"。
+  // Node fetch hides the real reason in err.cause (e.g. ECONNREFUSED /
+  // ENOTFOUND / self-signed certificate); err.message is usually just the
+  // generic "fetch failed".
   const cause = lastErr?.cause;
   const detail = cause?.code || cause?.message || lastErr?.message || String(lastErr);
-  throw new Error(`连接失败：${detail}`);
+  throw new Error(`Connection failed: ${detail}`);
 }
 
 async function handleResponse(res) {
@@ -73,7 +80,7 @@ async function handleResponse(res) {
     try {
       body = JSON.parse(text);
     } catch {
-      throw new Error(`非 JSON 响应（HTTP ${res.status}）：${text.slice(0, 200)}`);
+      throw new Error(`Non-JSON response (HTTP ${res.status}): ${text.slice(0, 200)}`);
     }
   }
 
@@ -85,7 +92,7 @@ async function handleResponse(res) {
     throw new ApiError(msg, code, res.status);
   }
 
-  // superjson 响应剥层
+  // Unwrap the superjson response
   return body.result.data.json;
 }
 
@@ -96,8 +103,8 @@ export async function trpcQuery(opts, proc, inputValue) {
 }
 
 export async function trpcMutation(opts, proc, inputValue) {
-  const url = buildUrl(opts.apiOrigin, proc); // mutation 不走 query input
-  // mutation 永远发 JSON body：input 为 undefined 时发 {"json": null}
+  const url = buildUrl(opts.apiOrigin, proc); // mutations don't use query input
+  // A mutation always sends a JSON body: {"json": null} when input is undefined
   const body = JSON.stringify({ json: inputValue === undefined ? null : inputValue });
   const res = await doRequest({ method: "POST", url, token: opts.token, body });
   return handleResponse(res);

package/lib/chat.mjs

@@ -0,0 +1,192 @@
+// chat capability: send one message to Neodrop's conversational agent, wait for
+// the reply to finish generating, and return the complete reply.
+//
+// Flow (everything uses the user's PAT with Bearer auth):
+//   1. Create / reuse a session: session.create (global assistant) or
+//      session.getOrCreateChannelAssistant (--channel assistant) — tRPC mutation.
+//   2. Send: POST /api/chat (a non-tRPC Hono endpoint; the backend has supported
+//      PAT Bearer since 2026-07). The response is an SSE stream; the reply is
+//      generated by a backend BullMQ worker decoupled from this connection's
+//      lifecycle, so the CLI does not parse the stream contents and only treats
+//      "the stream reached EOF" as a likely-done signal.
+//   3. Settle: poll session.getActiveChatTurn until null (the turn has reached a
+//      terminal state — this layer also covers a mid-stream SSE disconnect),
+//      then session.getMessages to take the messages added after this user
+//      message as the reply. Final consistency relies on getMessages, not the
+//      stream.
+//
+// Why we don't parse the SSE: the UIMessage chunk protocol has many types and
+// evolves with the main repo, and the CLI's consumer is an AI agent that wants
+// "the complete reply as JSON in one shot", not token-by-token rendering.
+
+import { randomUUID } from "node:crypto";
+import { trpcMutation, trpcQuery } from "./api.mjs";
+import { note } from "./output.mjs";
+
+const USER_AGENT = "neodrop-cli/1.0 (+https://github.com/NeoDropAI/neodrop-skills)";
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// POST /api/chat to send a message. On success returns the Response (the SSE
+// stream has started); on HTTP >= 400 it parses the JSON error and throws
+// (402 insufficient balance / 401 not logged in / 400 invalid message, etc.).
+async function postChatMessage({ apiOrigin, token, sessionId, text, locale, signal }) {
+  const url = `${apiOrigin.replace(/\/+$/, "")}/api/chat`;
+  const body = {
+    sessionId,
+    locale,
+    message: {
+      id: randomUUID(),
+      role: "user",
+      parts: [{ type: "text", text }],
+    },
+  };
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "user-agent": USER_AGENT,
+      authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(body),
+    signal,
+  });
+  if (res.status >= 400) {
+    let payload = null;
+    try {
+      payload = await res.json();
+    } catch {
+      // Non-JSON error body; fall back to the HTTP status
+    }
+    const msg = (payload && (payload.error || payload.message)) || `HTTP ${res.status}`;
+    const code = (payload && payload.code) || "";
+    throw new Error(code ? `[${code}] ${msg}` : `Send failed: ${msg}`);
+  }
+  return { response: res, userMessageId: body.message.id };
+}
+
+// Read the SSE stream to EOF (contents discarded). A disconnect / timeout is not
+// a failure — the backend worker is decoupled from the connection, and the final
+// state is settled by polling getActiveChatTurn.
+async function drainStream(response) {
+  try {
+    if (!response.body) return;
+    for await (const _chunk of response.body) {
+      // Just wait for EOF, don't parse
+    }
+  } catch {
+    note("⚠ SSE connection dropped, falling back to polling for the reply…");
+  }
+}
+
+// Poll until the session has no live chat turn (the reply has finished /
+// failed / been cancelled).
+async function pollUntilTurnSettled({ apiOrigin, token, sessionId, deadline, intervalMs }) {
+  for (;;) {
+    const turn = await trpcQuery({ apiOrigin, token }, "session.getActiveChatTurn", {
+      sessionId,
+    });
+    if (!turn) return;
+    if (Date.now() > deadline) {
+      throw new Error(
+        `Timed out waiting for the reply (turn=${turn.id} still ${turn.status}). You can check the result later with chat history --session ${sessionId}.`,
+      );
+    }
+    await sleep(intervalMs);
+  }
+}
+
+function extractText(parts) {
+  if (!Array.isArray(parts)) return "";
+  return parts
+    .filter((p) => p && p.type === "text" && typeof p.text === "string")
+    .map((p) => p.text)
+    .join("");
+}
+
+/**
+ * Send one message and wait for the complete reply.
+ *
+ * @returns {Promise<{sessionId: string, reply: {text: string, parts: unknown[]} | null, newMessages: unknown[]}>}
+ *   reply is the last assistant message among the newly added messages (text =
+ *   its text parts joined); in cases such as a failed turn there may be no
+ *   assistant reply, so reply is null and the caller decides based on newMessages.
+ */
+export async function sendAndAwaitReply({
+  apiOrigin,
+  token,
+  sessionId,
+  text,
+  locale,
+  timeoutMs,
+  pollIntervalMs,
+}) {
+  const deadline = Date.now() + timeoutMs;
+  const abort = AbortSignal.timeout(timeoutMs);
+
+  // Snapshot existing message ids before sending: the backend assigns the user
+  // message its own id (it does not echo the message.id we sent), so we can't use
+  // the client id as an anchor — we diff against "messages that appeared after
+  // sending".
+  const before = await trpcQuery({ apiOrigin, token }, "session.getMessages", {
+    sessionId,
+  });
+  const beforeIds = new Set(before.map((m) => m.id));
+
+  note(`→ Sending to session ${sessionId} …`);
+  const { response } = await postChatMessage({
+    apiOrigin,
+    token,
+    sessionId,
+    text,
+    locale,
+    signal: abort,
+  });
+
+  note("… generating reply");
+  await drainStream(response);
+  await pollUntilTurnSettled({
+    apiOrigin,
+    token,
+    sessionId,
+    deadline,
+    intervalMs: pollIntervalMs,
+  });
+
+  const messages = await trpcQuery({ apiOrigin, token }, "session.getMessages", {
+    sessionId,
+  });
+  // All messages added this round (the diff); dropping the user message we just
+  // sent leaves this round's reply (assistant text + intermediate artifacts such
+  // as tool / data cards).
+  const fresh = messages.filter((m) => !beforeIds.has(m.id));
+  const lastUserIdx = fresh.map((m) => m.role).lastIndexOf("user");
+  const newMessages = lastUserIdx >= 0 ? fresh.slice(lastUserIdx + 1) : fresh;
+  const lastAssistant = [...newMessages]
+    .reverse()
+    .find((m) => m.role === "assistant");
+
+  return {
+    sessionId,
+    reply: lastAssistant
+      ? { text: extractText(lastAssistant.parts), parts: lastAssistant.parts }
+      : null,
+    newMessages,
+  };
+}
+
+/** Create a new session (global assistant), or get the channel's assistant session per --channel. */
+export async function resolveChatSession({ apiOrigin, token, channelId }) {
+  if (channelId) {
+    const session = await trpcMutation(
+      { apiOrigin, token },
+      "session.getOrCreateChannelAssistant",
+      { channelId },
+    );
+    return session.id;
+  }
+  const session = await trpcMutation({ apiOrigin, token }, "session.create", {});
+  return session.id;
+}

package/lib/credentials.mjs

@@ -1,14 +1,16 @@
-// 本地凭证（~/.neodrop/credentials.json，chmod 0600）。
+// Local credentials (~/.neodrop/credentials.json, chmod 0600).
 //
-// 只支持单一 active token——切换 server / 换号都走 logout → login。
+// Only a single active token is supported — switching server / account goes
+// through logout → login.
 //
-// 凭证 schema：
-//   webOrigin  string  产品域（neodrop.ai；本地 dev 4001）
-//   apiOrigin  string  API 域（api.neodrop.ai；本地 dev 3001）—— 与 web 拆开是因为部署不同域
-//   token      string  PAT 明文，仅本机；权限 0600
-//   tokenId    string  用于 logout / 远程撤销
-//   name       string  在 /settings/cli-tokens 上展示的客户端名
-//   expiresAt  string  ISO 8601，默认 90 天
+// Credential schema:
+//   webOrigin  string  product origin (neodrop.ai; local dev 4001)
+//   apiOrigin  string  API origin (api.neodrop.ai; local dev 3001) — split from
+//                      web because they deploy on different domains
+//   token      string  PAT in plaintext, local machine only; mode 0600
+//   tokenId    string  used for logout / remote revocation
+//   name       string  client name shown on /settings/cli-tokens
+//   expiresAt  string  ISO 8601, defaults to 90 days
 //   createdAt  string  ISO 8601
 
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
@@ -27,12 +29,14 @@ export function readCredentials() {
   try {
     return JSON.parse(readFileSync(FILE_PATH, "utf-8"));
   } catch (err) {
-    throw new Error(`无法解析 ${FILE_PATH}：${err.message}`);
+    throw new Error(`Failed to parse ${FILE_PATH}: ${err.message}`);
   }
 }
 
-// 原子写：写临时文件 → chmod 0600 → rename。chmod 在 rename 之前完成，确保最终
-// 文件出现的瞬间权限就是 0600，不存在其他进程能读到 world-readable 的窗口。
+// Atomic write: write temp file → chmod 0600 → rename. The chmod completes
+// before the rename, guaranteeing the final file has 0600 permissions the moment
+// it appears — there is no window where another process could read it as
+// world-readable.
 export function writeCredentials(creds) {
   mkdirSync(FILE_DIR, { recursive: true });
   const tmp = `${FILE_PATH}.tmp`;
@@ -52,7 +56,7 @@ export function clearCredentials() {
 export function requireCredentials() {
   const creds = readCredentials();
   if (creds === null) {
-    throw new Error("未登录。先运行：npx neodrop-cli login");
+    throw new Error("Not logged in. Run: npx neodrop-cli login");
   }
   return creds;
 }

package/lib/install-skill.mjs

@@ -1,12 +1,15 @@
-// 把 SKILL.md + references/ 拷进 agent 的 skill 目录，让 `npx neodrop-cli` 一条命令
-// 既装好 CLI 又装好 skill 描述。
+// Copy SKILL.md + references/ into the agent's skill directory so that a single
+// `npx neodrop-cli` command installs both the CLI and the skill description.
 //
-// npm/npx 只分发「可执行文件」；而 Claude Code 等 agent 的 skill 是 SKILL.md +
-// references/ 这组文件落进 agent 的 skill 目录后才会被路由。两条分发渠道本来是
-// 分开的，这个命令把它们合并成一步。
+// npm/npx only distributes "executables"; an agent skill for Claude Code and the
+// like is the SKILL.md + references/ file set, which is only routed once it lands
+// in the agent's skill directory. The two distribution channels are normally
+// separate, and this command merges them into one step.
 //
-// 默认目标 ~/.claude/skills/neodrop-cli/（Claude Code 约定）；--dest 可改到别的
-// agent 的 skill 目录。目录名固定 neodrop-cli，与 SKILL.md frontmatter 的 name 一致。
+// The default target is ~/.claude/skills/neodrop-cli/ (the Claude Code
+// convention); --dest can point at another agent's skill directory. The
+// directory name is fixed to neodrop-cli, matching the name in SKILL.md's
+// frontmatter.
 
 import { cpSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
@@ -18,14 +21,14 @@ export function defaultSkillDest() {
 }
 
 export function installSkill({ dest } = {}) {
-  // 包根目录 = 本文件所在 lib/ 的上一层（bin/ 与 lib/ 与 SKILL.md 同级）
+  // Package root = the parent of this file's lib/ dir (bin/, lib/, and SKILL.md are siblings)
   const here = dirname(fileURLToPath(import.meta.url)); // .../lib
   const pkgRoot = dirname(here);
   const target = dest || defaultSkillDest();
 
   const skillSrc = join(pkgRoot, "SKILL.md");
   if (!existsSync(skillSrc)) {
-    throw new Error(`找不到 SKILL.md（期望在 ${skillSrc}）；npm 包可能未按 files 白名单打进 SKILL.md`);
+    throw new Error(`SKILL.md not found (expected at ${skillSrc}); the npm package may not have included SKILL.md in its files allowlist`);
   }
 
   mkdirSync(target, { recursive: true });

package/lib/origins.mjs

@@ -1,10 +1,13 @@
-// Neodrop 部署的 web origin（产品域）与 api origin（backend 域）解耦。
+// Neodrop deploys the web origin (product domain) and api origin (backend
+// domain) decoupled.
 //
-// 线上：web = https://neodrop.ai，api = https://api.neodrop.ai
-// 本地 dev：web = http://localhost:4001，api = http://localhost:3001
+// Production: web = https://neodrop.ai, api = https://api.neodrop.ai
+// Local dev:  web = http://localhost:4001, api = http://localhost:3001
 //
-// CLI 让用户显式传 --api；不传时按 web origin 启发式推断。self-host 用户默认
-// 假设 backend 反代到 web 同域 /trpc/*，需要时用 --api 覆盖。
+// The CLI lets the user pass --api explicitly; when omitted it is inferred
+// heuristically from the web origin. For self-hosted users the default assumes
+// the backend is reverse-proxied on the same domain as web at /trpc/*, which can
+// be overridden with --api when needed.
 
 export function inferApiOrigin(webOrigin) {
   let parsed;
@@ -17,16 +20,17 @@ export function inferApiOrigin(webOrigin) {
   const port = parsed.port;
   const scheme = parsed.protocol.replace(/:$/, "");
 
-  // 线上 neodrop.ai → api.neodrop.ai
+  // Production neodrop.ai → api.neodrop.ai
   if (host === "neodrop.ai") {
     return `${scheme}://api.neodrop.ai`;
   }
 
-  // 本地 dev：localhost:4001 / 127.0.0.1:4001 → 同 host 3001
+  // Local dev: localhost:4001 / 127.0.0.1:4001 → same host on 3001
   if ((host === "localhost" || host === "127.0.0.1") && port === "4001") {
     return `${scheme}://${host}:3001`;
   }
 
-  // 其他（self-host 反代等）：默认与 web 同域，假设 /trpc/* 反代到 backend。
+  // Otherwise (self-host reverse proxy, etc.): default to the same domain as
+  // web, assuming /trpc/* is proxied to the backend.
   return webOrigin.replace(/\/+$/, "");
 }

package/lib/output.mjs

@@ -1,7 +1,7 @@
-// 统一输出：stdout = JSON（AI 直接 JSON.parse），stderr = 日志/提示。
+// Unified output: stdout = JSON (an AI can JSON.parse directly), stderr = logs/notices.
 //
-// 默认单行 JSON；--pretty 切 2 空格缩进 JSON——两者都是合法 JSON，AI 不需要
-// flag 切换也能解析。
+// Single-line JSON by default; --pretty switches to 2-space indented JSON — both
+// are valid JSON, so an AI can parse either without needing the flag.
 
 let pretty = false;
 

package/lib/web-urls.mjs

@@ -1,17 +1,23 @@
-// Neodrop 前端 URL 拼装：用户拿到 id 后能直接得到一条可点击的网页链接。
+// Neodrop frontend URL assembly: once a user has an id, they get a clickable web
+// link directly.
 //
-// 为什么放 skill 而不是后端 response：URL 路径（`/post/<id>` / `/channel/<id>` /
-// `/user/<id>`）是前端的渲染契约，不是数据契约——`grain.id` 是稳定的数据；前端
-// 明天可以把路由改成 `/post/<id>` 而无需后端发新版 API。把路由塞进 response 会让
-// backend 反向依赖前端渲染。这里给 CLI 内部用，作为 stderr 上的人类可读提示。
+// Why this lives in the skill rather than the backend response: URL paths
+// (`/post/<id>` / `/channel/<id>` / `/user/<id>`) are a frontend rendering
+// contract, not a data contract — `grain.id` is stable data; the frontend could
+// change the route to `/post/<id>` tomorrow without the backend shipping a new
+// API version. Baking routes into the response would make the backend depend
+// backwards on frontend rendering. This is for CLI internal use, as a
+// human-readable hint on stderr.
 //
-// 路径权威源 = `apps/web/src/app/[locale]/<route>/[id]/page.tsx`：
+// Path source of truth = `apps/web/src/app/[locale]/<route>/[id]/page.tsx`:
 //   post / grain  → `/post/<id>`
 //   channel       → `/channel/<id>`
 //   user          → `/user/<id>`
 //
-// 注意：CLI 不挂 locale 前缀（neodrop.ai 的 localePrefix='as-needed'，默认 locale
-// `en` 落到无前缀路径；其它 locale 由前端按用户偏好做客户端 redirect）。
+// Note: the CLI attaches no locale prefix (neodrop.ai uses
+// localePrefix='as-needed', so the default locale `en` maps to the prefix-less
+// path; other locales are handled by a client-side redirect based on user
+// preference).
 
 function strip(origin) {
   return origin.replace(/\/+$/, "");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "neodrop-cli",
-  "version": "1.1.0",
-  "description": "Neodrop (neodrop.ai) CLI — let your AI agent (Claude Code / Cursor / Codex) browse channels, read posts, manage subscriptions and create channels as you. stdout is always valid JSON. npx neodrop-cli login and go.",
+  "version": "2.0.0",
+  "description": "Neodrop (neodrop.ai) CLI — let your AI agent (Claude Code / Cursor / Codex) browse channels, read posts, manage subscriptions, create channels and chat with Neodrop's AI assistants as you. stdout is always valid JSON. npx neodrop-cli login and go.",
   "type": "module",
   "bin": {
     "neodrop": "bin/neodrop.mjs"