@jackwener/opencli 1.5.4 → 1.5.6

package/src/clis/ones/common.ts

@@ -0,0 +1,187 @@
+/**
+ * ONES 旧版 Project API — 经 Browser Bridge 在已登录标签页内 fetch（携带 Cookie）。
+ * 文档：https://developer.ones.cn/zh-CN/docs/api/readme/
+ */
+
+import type { IPage } from '../../types.js';
+import { CliError } from '../../errors.js';
+
+export const API_PREFIX = '/project/api/project';
+
+export function getOnesBaseUrl(): string {
+  const u = process.env.ONES_BASE_URL?.trim().replace(/\/+$/, '');
+  if (!u) {
+    throw new CliError(
+      'CONFIG',
+      'Missing ONES_BASE_URL',
+      'Set ONES_BASE_URL to your deployment origin, e.g. https://your-team.ones.cn (no trailing slash).',
+    );
+  }
+  return u;
+}
+
+export function onesApiUrl(apiPath: string): string {
+  const base = getOnesBaseUrl();
+  const p = apiPath.replace(/^\/+/, '');
+  return `${base}${API_PREFIX}/${p}`;
+}
+
+/** 打开 ONES 根地址，确保后续 fetch 与页面同源、带上登录 Cookie */
+export async function gotoOnesHome(page: IPage): Promise<void> {
+  await page.goto(getOnesBaseUrl(), { waitUntil: 'load' });
+  await page.wait(2);
+}
+
+/**
+ * 在页面内发起请求。默认带 credentials；若设置了 ONES_USER_ID + ONES_AUTH_TOKEN，则附加文档要求的 Header（与纯 Cookie 二选一或并存，取决于部署）。
+ */
+function buildHeaders(auth: boolean, includeJsonContentType: boolean): Record<string, string> {
+  const ref = getOnesBaseUrl();
+  const out: Record<string, string> = { Referer: ref };
+  if (auth) {
+    const uid =
+      process.env.ONES_USER_ID?.trim() ||
+      process.env.ONES_USER_UUID?.trim() ||
+      process.env.Ones_User_Id?.trim();
+    const tok = process.env.ONES_AUTH_TOKEN?.trim() || process.env.Ones_Auth_Token?.trim();
+    if (uid && tok) {
+      out['Ones-User-Id'] = uid;
+      out['Ones-Auth-Token'] = tok;
+    }
+  }
+  if (includeJsonContentType) out['Content-Type'] = 'application/json';
+  return out;
+}
+
+export function summarizeOnesError(status: number, body: unknown): string {
+  if (body && typeof body === 'object') {
+    const o = body as Record<string, unknown>;
+    const parts: string[] = [];
+    if (typeof o.type === 'string') parts.push(o.type);
+    if (typeof o.reason === 'string') parts.push(o.reason);
+    if (typeof o.errcode === 'string') parts.push(o.errcode);
+    if (typeof o.message === 'string') parts.push(o.message);
+    if (o.code !== undefined && o.code !== null) parts.push(`code=${String(o.code)}`);
+    if (parts.length) return parts.filter(Boolean).join(' · ');
+  }
+  return status === 401 ? 'Unauthorized' : `HTTP ${status}`;
+}
+
+/** ONES 部分接口 HTTP 200 但 body 仍为错误（如 reason: ServerError） */
+function throwIfOnesPeekBusinessError(apiPath: string, parsed: unknown): void {
+  if (parsed === null || typeof parsed !== 'object') return;
+  const o = parsed as Record<string, unknown>;
+  if (Array.isArray(o.groups)) return;
+  const hasErr =
+    (typeof o.reason === 'string' && o.reason.length > 0) ||
+    (typeof o.errcode === 'string' && o.errcode.length > 0) ||
+    (typeof o.type === 'string' && o.type.length > 0);
+  if (!hasErr) return;
+  const detail = summarizeOnesError(200, parsed);
+  throw new CliError(
+    'FETCH_ERROR',
+    `ONES ${apiPath}: ${detail}`,
+    '若 query 不合法会返回 ServerError；可试 opencli ones tasks（空 must）或检查筛选器文档。响应全文可用 -v 或临时打日志。',
+  );
+}
+
+export async function onesFetchInPageWithMeta(
+  page: IPage,
+  apiPath: string,
+  options: {
+    method?: string;
+    body?: string | null;
+    auth?: boolean;
+    skipGoto?: boolean;
+  } = {},
+): Promise<{ ok: boolean; status: number; parsed: unknown }> {
+  if (!options.skipGoto) {
+    await gotoOnesHome(page);
+  }
+
+  const url = onesApiUrl(apiPath);
+  const method = (options.method ?? 'GET').toUpperCase();
+  const auth = options.auth !== false;
+  const body = options.body ?? null;
+  const includeCt = body !== null || method === 'POST' || method === 'PUT' || method === 'PATCH';
+  const headers = buildHeaders(auth, includeCt);
+
+  const urlJs = JSON.stringify(url);
+  const methodJs = JSON.stringify(method);
+  const headersJs = JSON.stringify(headers);
+  const bodyJs = body === null ? 'null' : JSON.stringify(body);
+
+  const raw = await page.evaluate(`
+    (async () => {
+      const url = ${urlJs};
+      const method = ${methodJs};
+      const headers = ${headersJs};
+      const body = ${bodyJs};
+      const init = {
+        method,
+        headers: { ...headers },
+        credentials: 'include',
+      };
+      if (body !== null) init.body = body;
+      const res = await fetch(url, init);
+      const text = await res.text();
+      let parsed = null;
+      try {
+        parsed = text ? JSON.parse(text) : null;
+      } catch {
+        parsed = text;
+      }
+      return { ok: res.ok, status: res.status, parsed };
+    })()
+  `);
+
+  return raw as { ok: boolean; status: number; parsed: unknown };
+}
+
+/** 当前操作用户 8 位 uuid（Header 或 GET users/me） */
+export async function resolveOnesUserUuid(page: IPage, opts?: { skipGoto?: boolean }): Promise<string> {
+  const fromEnv =
+    process.env.ONES_USER_ID?.trim() ||
+    process.env.ONES_USER_UUID?.trim() ||
+    process.env.Ones_User_Id?.trim();
+  if (fromEnv) return fromEnv;
+
+  const data = (await onesFetchInPage(page, 'users/me', { skipGoto: opts?.skipGoto })) as Record<string, unknown>;
+  const u = data.user && typeof data.user === 'object' ? (data.user as Record<string, unknown>) : data;
+  if (!u || typeof u.uuid !== 'string') {
+    throw new CliError(
+      'FETCH_ERROR',
+      'Could not read current user uuid from users/me',
+      'Set ONES_USER_ID or ensure Chrome is logged in; try: opencli ones me -f json',
+    );
+  }
+  return String(u.uuid);
+}
+
+export async function onesFetchInPage(
+  page: IPage,
+  apiPath: string,
+  options: {
+    method?: string;
+    body?: string | null;
+    auth?: boolean;
+    /** 已在 ONES 根页时设为 true，避免每条 API 都 goto+wait（显著提速） */
+    skipGoto?: boolean;
+  } = {},
+): Promise<unknown> {
+  const r = await onesFetchInPageWithMeta(page, apiPath, options);
+  if (!r.ok) {
+    const detail = summarizeOnesError(r.status, r.parsed);
+    const hint =
+      r.status === 401
+        ? '在 Chrome 中打开 ONES 并登录；或先执行 opencli ones login 后按提示 export ONES_USER_ID / ONES_AUTH_TOKEN；并确认 ONES_BASE_URL 与浏览器地址一致。'
+        : '检查 ONES_BASE_URL、VPN/内网，以及实例是否仍为 Project API 路径。';
+    throw new CliError('FETCH_ERROR', `ONES ${apiPath}: ${detail}`, hint);
+  }
+
+  if (apiPath.includes('/filters/peek')) {
+    throwIfOnesPeekBusinessError(apiPath, r.parsed);
+  }
+
+  return r.parsed;
+}

package/src/clis/ones/enrich-tasks.ts

@@ -0,0 +1,47 @@
+/**
+ * peek 列表只有轻量字段，用 batch tasks/info 补全 summary 等（ONES 文档 #7）
+ */
+
+import type { IPage } from '../../types.js';
+import { onesFetchInPage } from './common.js';
+
+const BATCH_SIZE = 40;
+
+export async function enrichPeekEntriesWithDetails(
+  page: IPage,
+  team: string,
+  entries: Record<string, unknown>[],
+  skipGoto: boolean,
+): Promise<Record<string, unknown>[]> {
+  const ids = [...new Set(entries.map((e) => String(e.uuid ?? '').trim()).filter(Boolean))];
+  if (ids.length === 0) return entries;
+
+  const byId = new Map<string, Record<string, unknown>>();
+
+  try {
+    for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+      const slice = ids.slice(i, i + BATCH_SIZE);
+      const parsed = (await onesFetchInPage(page, `team/${team}/tasks/info`, {
+        method: 'POST',
+        body: JSON.stringify({ ids: slice }),
+        skipGoto,
+      })) as Record<string, unknown>;
+
+      const tasks = Array.isArray(parsed.tasks) ? (parsed.tasks as Record<string, unknown>[]) : [];
+      for (const t of tasks) {
+        const id = String(t.uuid ?? '');
+        if (id) byId.set(id, t);
+      }
+    }
+  } catch {
+    return entries;
+  }
+
+  if (byId.size === 0) return entries;
+
+  return entries.map((e) => {
+    const id = String(e.uuid ?? '');
+    const full = id ? byId.get(id) : undefined;
+    return full ? { ...e, ...full } : e;
+  });
+}

package/src/clis/ones/login.ts

@@ -0,0 +1,103 @@
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { getOnesBaseUrl, onesFetchInPage } from './common.js';
+
+cli({
+  site: 'ones',
+  name: 'login',
+  description:
+    'ONES Project API — login via Chrome Bridge (POST auth/login); stderr prints export hints for ONES_USER_ID / TOKEN',
+  domain: 'ones.cn',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    {
+      name: 'email',
+      type: 'str',
+      required: false,
+      help: 'Account email (or set ONES_EMAIL)',
+    },
+    {
+      name: 'phone',
+      type: 'str',
+      required: false,
+      help: 'Account phone (or set ONES_PHONE); ignored if email is set',
+    },
+    {
+      name: 'password',
+      type: 'str',
+      required: false,
+      help: 'Password (or set ONES_PASSWORD)',
+    },
+  ],
+  columns: ['uuid', 'name', 'email', 'token_preview'],
+
+  func: async (page, kwargs) => {
+    const email = (kwargs.email as string | undefined)?.trim() || process.env.ONES_EMAIL?.trim();
+    const phone = (kwargs.phone as string | undefined)?.trim() || process.env.ONES_PHONE?.trim();
+    const password =
+      (kwargs.password as string | undefined) || process.env.ONES_PASSWORD || '';
+
+    if (!password) {
+      throw new CliError(
+        'CONFIG',
+        'Password required',
+        'Pass --password or set ONES_PASSWORD for non-interactive use.',
+      );
+    }
+    if (!email && !phone) {
+      throw new CliError(
+        'CONFIG',
+        'email or phone required',
+        'Pass --email or --phone (or set ONES_EMAIL / ONES_PHONE).',
+      );
+    }
+
+    getOnesBaseUrl();
+    const bodyObj: Record<string, string> = { password };
+    if (email) bodyObj.email = email;
+    else bodyObj.phone = phone!;
+
+    const parsed = (await onesFetchInPage(page, 'auth/login', {
+      method: 'POST',
+      body: JSON.stringify(bodyObj),
+      auth: false,
+    })) as Record<string, unknown>;
+
+    const user = parsed.user as Record<string, unknown> | undefined;
+    if (!user?.uuid || !user?.token) {
+      throw new CliError(
+        'FETCH_ERROR',
+        'ONES login response missing user.uuid or user.token',
+        'Your server build may differ from documented Project API.',
+      );
+    }
+
+    const uuid = String(user.uuid);
+    const token = String(user.token);
+    const name = String(user.name ?? '');
+    const em = String(user.email ?? '');
+
+    const base = getOnesBaseUrl();
+    console.error(
+      [
+        '',
+        '后续请求会优先使用当前 Chrome 会话 Cookie；若接口仍要求 Header，可 export：',
+        `  export ONES_BASE_URL=${JSON.stringify(base)}`,
+        `  export ONES_USER_ID=${JSON.stringify(uuid)}`,
+        `  export ONES_AUTH_TOKEN=${JSON.stringify(token)}`,
+        '',
+      ].join('\n'),
+    );
+
+    return [
+      {
+        uuid,
+        name,
+        email: em,
+        token_preview: token.length > 12 ? `${token.slice(0, 6)}…${token.slice(-4)}` : '***',
+      },
+    ];
+  },
+});

package/src/clis/ones/logout.ts

@@ -0,0 +1,19 @@
+import { cli, Strategy } from '../../registry.js';
+import { onesFetchInPage } from './common.js';
+
+cli({
+  site: 'ones',
+  name: 'logout',
+  description: 'ONES Project API — invalidate current token (GET auth/logout) via Chrome Bridge',
+  domain: 'ones.cn',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [],
+  columns: ['ok', 'detail'],
+
+  func: async (page) => {
+    await onesFetchInPage(page, 'auth/logout', { method: 'GET' });
+    return [{ ok: 'true', detail: 'Server logout ok; clear local ONES_AUTH_TOKEN if set.' }];
+  },
+});

package/src/clis/ones/me.ts

@@ -0,0 +1,34 @@
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import { onesFetchInPage } from './common.js';
+
+cli({
+  site: 'ones',
+  name: 'me',
+  description: 'ONES Project API — current user (GET users/me) via Chrome Bridge',
+  domain: 'ones.cn',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [],
+  columns: ['uuid', 'name', 'email', 'phone', 'status'],
+
+  func: async (page) => {
+    const data = (await onesFetchInPage(page, 'users/me')) as Record<string, unknown>;
+    const u = data.user && typeof data.user === 'object' ? (data.user as Record<string, unknown>) : data;
+
+    if (!u || typeof u.uuid !== 'string') {
+      throw new CliError('FETCH_ERROR', 'Unexpected users/me response', 'See raw JSON with: opencli ones me -f json');
+    }
+
+    return [
+      {
+        uuid: String(u.uuid),
+        name: String(u.name ?? ''),
+        email: String(u.email ?? ''),
+        phone: String(u.phone ?? ''),
+        status: u.status != null ? String(u.status) : '',
+      },
+    ];
+  },
+});

package/src/clis/ones/my-tasks.ts

@@ -0,0 +1,148 @@
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+import type { IPage } from '../../types.js';
+import { gotoOnesHome, onesFetchInPage, resolveOnesUserUuid } from './common.js';
+import { enrichPeekEntriesWithDetails } from './enrich-tasks.js';
+import { resolveTaskListLabels } from './resolve-labels.js';
+import {
+  defaultPeekBody,
+  flattenPeekGroups,
+  mapTaskEntry,
+  parsePeekLimit,
+} from './task-helpers.js';
+
+/** 文档示例里「负责人」常用 field004；与顶层 assign 在不同部署上二选一有效 */
+function queryAssign(userUuid: string): Record<string, unknown> {
+  return { must: [{ equal: { assign: userUuid } }] };
+}
+
+function queryAssignField004(userUuid: string): Record<string, unknown> {
+  return { must: [{ in: { 'field_values.field004': [userUuid] } }] };
+}
+
+function queryOwner(userUuid: string): Record<string, unknown> {
+  return { must: [{ equal: { owner: userUuid } }] };
+}
+
+function dedupeByUuid(entries: Record<string, unknown>[]): Record<string, unknown>[] {
+  const seen = new Set<string>();
+  const out: Record<string, unknown>[] = [];
+  for (const e of entries) {
+    const id = String(e.uuid ?? '');
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    out.push(e);
+  }
+  return out;
+}
+
+async function peekTasks(
+  page: IPage,
+  team: string,
+  query: Record<string, unknown>,
+  cap: number,
+): Promise<Record<string, unknown>[]> {
+  const path = `team/${team}/filters/peek`;
+  const body = defaultPeekBody(query);
+  const parsed = (await onesFetchInPage(page, path, {
+    method: 'POST',
+    body: JSON.stringify(body),
+    skipGoto: true,
+  })) as Record<string, unknown>;
+  return flattenPeekGroups(parsed, cap);
+}
+
+cli({
+  site: 'ones',
+  name: 'my-tasks',
+  description:
+    'ONES — my work items (filters/peek + strict must query). Default: assignee=me. Use --mode if your site uses field004 for assignee.',
+  domain: 'ones.cn',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    {
+      name: 'team',
+      type: 'str',
+      required: false,
+      positional: true,
+      help: 'Team UUID from URL …/team/<uuid>/…, or set ONES_TEAM_UUID',
+    },
+    {
+      name: 'limit',
+      type: 'int',
+      default: 100,
+      help: 'Max rows (default 100, max 500)',
+    },
+    {
+      name: 'mode',
+      type: 'str',
+      default: 'assign',
+      choices: ['assign', 'field004', 'owner', 'both'],
+      help:
+        'assign=负责人(顶层 assign)；field004=负责人(筛选器示例里的 field004)；owner=创建者；both=负责人∪创建者(两次 peek 去重)',
+    },
+  ],
+  columns: ['title', 'status', 'project', 'uuid', 'updated', '工时'],
+
+  func: async (page, kwargs) => {
+    const team =
+      (kwargs.team as string | undefined)?.trim() ||
+      process.env.ONES_TEAM_UUID?.trim() ||
+      process.env.ONES_TEAM_ID?.trim();
+    if (!team) {
+      throw new CliError(
+        'CONFIG',
+        'team UUID required',
+        'Pass team from URL …/team/<team>/… or set ONES_TEAM_UUID.',
+      );
+    }
+
+    const limit = parsePeekLimit(kwargs.limit, 100);
+    const mode = String(kwargs.mode ?? 'assign');
+
+    await gotoOnesHome(page);
+    const userUuid = await resolveOnesUserUuid(page, { skipGoto: true });
+
+    let entries: Record<string, unknown>[] = [];
+
+    if (mode === 'both') {
+      const cap = Math.min(500, limit * 2);
+      const asAssign = await peekTasks(page, team, queryAssign(userUuid), cap);
+      const asOwner = await peekTasks(page, team, queryOwner(userUuid), cap);
+      entries = dedupeByUuid([...asAssign, ...asOwner]).slice(0, limit);
+    } else {
+      const queryByMode = (): Record<string, unknown> => {
+        switch (mode) {
+          case 'field004':
+            return queryAssignField004(userUuid);
+          case 'owner':
+            return queryOwner(userUuid);
+          case 'assign':
+          default:
+            return queryAssign(userUuid);
+        }
+      };
+
+      const primary = queryByMode();
+      try {
+        entries = await peekTasks(page, team, primary, limit);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : '';
+        const canFallback =
+          mode === 'assign' &&
+          (msg.includes('ServerError') || msg.includes('801') || msg.includes('Params is invalid'));
+        if (canFallback) {
+          entries = await peekTasks(page, team, queryAssignField004(userUuid), limit);
+        } else {
+          throw e;
+        }
+      }
+    }
+
+    const enriched = await enrichPeekEntriesWithDetails(page, team, entries, true);
+    const labels = await resolveTaskListLabels(page, team, enriched, true);
+    return enriched.map((e) => mapTaskEntry(e, labels));
+  },
+});

package/src/clis/ones/resolve-labels.ts

@@ -0,0 +1,80 @@
+/**
+ * 把 status / project 的 uuid 解析为中文名（团队级接口各查一次或按批）
+ */
+
+import type { IPage } from '../../types.js';
+import { onesFetchInPage } from './common.js';
+import { getTaskProjectRawId } from './task-helpers.js';
+
+export async function loadTaskStatusLabels(
+  page: IPage,
+  team: string,
+  skipGoto: boolean,
+): Promise<Map<string, string>> {
+  const map = new Map<string, string>();
+  try {
+    const parsed = (await onesFetchInPage(page, `team/${team}/task_statuses`, {
+      method: 'GET',
+      skipGoto,
+    })) as Record<string, unknown>;
+    const list = Array.isArray(parsed.task_statuses)
+      ? (parsed.task_statuses as Record<string, unknown>[])
+      : [];
+    for (const s of list) {
+      const id = String(s.uuid ?? '');
+      const name = String(s.name ?? '');
+      if (id && name) map.set(id, name);
+    }
+  } catch {
+    /* 降级为仅显示 uuid */
+  }
+  return map;
+}
+
+const PROJECT_INFO_CHUNK = 25;
+
+export async function loadProjectLabels(
+  page: IPage,
+  team: string,
+  projectUuids: string[],
+  skipGoto: boolean,
+): Promise<Map<string, string>> {
+  const map = new Map<string, string>();
+  const ids = [...new Set(projectUuids.filter(Boolean))];
+  if (ids.length === 0) return map;
+
+  try {
+    for (let i = 0; i < ids.length; i += PROJECT_INFO_CHUNK) {
+      const slice = ids.slice(i, i + PROJECT_INFO_CHUNK);
+      const q = slice.map(encodeURIComponent).join(',');
+      const path = `team/${team}/projects/info?ids=${q}`;
+      const parsed = (await onesFetchInPage(page, path, {
+        method: 'GET',
+        skipGoto,
+      })) as Record<string, unknown>;
+      const projects = Array.isArray(parsed.projects) ? (parsed.projects as Record<string, unknown>[]) : [];
+      for (const p of projects) {
+        const id = String(p.uuid ?? '');
+        const name = String(p.name ?? '');
+        if (id && name) map.set(id, name);
+      }
+    }
+  } catch {
+    /* 降级 */
+  }
+  return map;
+}
+
+export async function resolveTaskListLabels(
+  page: IPage,
+  team: string,
+  entries: Record<string, unknown>[],
+  skipGoto: boolean,
+): Promise<{ statusByUuid: Map<string, string>; projectByUuid: Map<string, string> }> {
+  const projectUuids = entries.map((e) => getTaskProjectRawId(e)).filter(Boolean);
+  const [statusByUuid, projectByUuid] = await Promise.all([
+    loadTaskStatusLabels(page, team, skipGoto),
+    loadProjectLabels(page, team, projectUuids, skipGoto),
+  ]);
+  return { statusByUuid, projectByUuid };
+}

package/src/clis/ones/task-helpers.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { parsePeekLimit } from './task-helpers.js';
+
+describe('parsePeekLimit', () => {
+  it('returns the fallback when the input is not numeric', () => {
+    expect(parsePeekLimit('abc', 30)).toBe(30);
+  });
+
+  it('clamps the input into the supported range', () => {
+    expect(parsePeekLimit('0', 30)).toBe(30);
+    expect(parsePeekLimit('999', 30)).toBe(500);
+    expect(parsePeekLimit('42', 30)).toBe(42);
+  });
+});