feishu-user-plugin 1.3.6 → 1.3.8

package/scripts/decode-feishu-protobuf.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict';
+// Decode a captured Feishu protobuf payload against proto/lark.proto.
+//
+// Usage:
+//   node scripts/decode-feishu-protobuf.js Packet            < /path/to/payload.bin
+//   echo "0a..." | node scripts/decode-feishu-protobuf.js Packet --hex
+//   node scripts/decode-feishu-protobuf.js Packet --b64 'CgRwYWNr...'
+//
+// Output:
+//   - Decoded JSON of the named message
+//   - "Unknown fields detected" section listing tag numbers + wire types we
+//     don't have in the proto (these are what we need to add).
+
+const path = require('path');
+const protobuf = require('protobufjs');
+
+async function main() {
+  const args = process.argv.slice(2);
+  const messageName = args[0];
+  if (!messageName) {
+    console.error('Usage: node scripts/decode-feishu-protobuf.js <MessageName> [--hex | --b64 <data>]');
+    process.exit(2);
+  }
+  const flagIdx = args.indexOf('--hex');
+  const b64Idx = args.indexOf('--b64');
+
+  let buf;
+  if (b64Idx !== -1) {
+    buf = Buffer.from(args[b64Idx + 1], 'base64');
+  } else if (flagIdx !== -1) {
+    const hex = await readStdin();
+    buf = Buffer.from(hex.replace(/\s+/g, ''), 'hex');
+  } else {
+    buf = await readStdinBuffer();
+  }
+
+  const proto = await protobuf.load(path.join(__dirname, '..', 'proto', 'lark.proto'));
+  const T = proto.lookupType(messageName);
+  const decoded = T.decode(buf);
+  const obj = T.toObject(decoded, { defaults: false, bytes: String });
+  // Walk the buffer to find unknown field tags.
+  const unknown = scanUnknownFields(buf, T);
+  console.log(JSON.stringify(obj, _dumpBytes, 2));
+  if (unknown.length) {
+    console.log('\n--- Unknown fields detected ---');
+    for (const u of unknown) console.log(`  field ${u.tag} (wire type ${u.wireType}, ${u.length} bytes): ${u.preview}`);
+    console.log('\nFor each unknown tag, add the field to proto/lark.proto and re-run to see the decoded shape.');
+  } else {
+    console.log('\n--- All fields known ---');
+  }
+}
+
+function _dumpBytes(_, v) {
+  if (Buffer.isBuffer(v)) return `<${v.length} bytes 0x${v.slice(0, 16).toString('hex')}${v.length > 16 ? '…' : ''}>`;
+  return v;
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    process.stdin.on('data', (c) => chunks.push(c));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+  });
+}
+
+function readStdinBuffer() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    process.stdin.on('data', (c) => chunks.push(c));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks)));
+  });
+}
+
+// Walks raw protobuf bytes, decoding tag headers, and reports tags whose
+// number+wireType is not present in the schema. Matches protobufjs's reader
+// state machine but operates entry-point-only (no recursion into subtrees).
+function scanUnknownFields(buf, type) {
+  const known = new Set(type.fieldsArray.map(f => f.id));
+  const reader = protobuf.Reader.create(buf);
+  const out = [];
+  while (reader.pos < reader.len) {
+    const tagInt = reader.uint32();
+    const tag = tagInt >>> 3;
+    const wireType = tagInt & 7;
+    const start = reader.pos;
+    let value;
+    try {
+      value = readValueByWireType(reader, wireType);
+    } catch (e) {
+      out.push({ tag, wireType, length: 0, preview: `decode error: ${e.message}` });
+      break;
+    }
+    if (!known.has(tag)) {
+      const len = reader.pos - start;
+      let preview;
+      if (Buffer.isBuffer(value)) preview = `0x${value.slice(0, 24).toString('hex')}${value.length > 24 ? '…' : ''}`;
+      else preview = String(value).slice(0, 80);
+      out.push({ tag, wireType, length: len, preview });
+    }
+  }
+  return out;
+}
+
+function readValueByWireType(reader, wireType) {
+  switch (wireType) {
+    case 0: return reader.uint64();        // varint
+    case 1: return reader.fixed64();       // 64-bit
+    case 2: return Buffer.from(reader.bytes()); // length-delimited
+    case 5: return reader.fixed32();       // 32-bit
+    default: reader.skipType(wireType); return null;
+  }
+}
+
+main().catch(e => { console.error('Error:', e.message); process.exit(1); });

package/scripts/smoke.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// scripts/smoke.js — MCP smoke test for refactor before/after diff.
+// Spawns src/index.js as a child via stdio, sends:
+//   1. tools/list                   → dumps sorted (name, description, inputSchema) to stdout
+//   2. tools/call get_login_status  → dumps recursive Object.keys (not values) to stdout
+//   3. prompts/list                 → dumps sorted (name, description, arguments) to stdout
+// Exits 0 on success, 1 on protocol error. Diff output against tests/baseline/*.json.
+//
+// Cred sourcing: src/index.js only reads process.env.LARK_*; this script injects
+// creds from ~/.claude.json via readCredentials() so the spawned MCP server has
+// the same auth it would have when launched by Claude Code. Without this the
+// baseline captures the not-configured login_status shape.
+//
+// Usage:
+//   node scripts/smoke.js dump            # print normalized current snapshot to stdout
+//   node scripts/smoke.js diff            # compare against tests/baseline/* and exit non-zero on mismatch
+//   node scripts/smoke.js write-baseline  # overwrite tests/baseline/*.json with current snapshot
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const { readCredentials } = require('../src/config');
+
+const SERVER_PATH = path.join(__dirname, '..', 'src', 'index.js');
+const BASELINE_DIR = path.join(__dirname, '..', 'tests', 'baseline');
+const TOOLS_BASELINE = path.join(BASELINE_DIR, 'tools-list.json');
+const LOGIN_BASELINE = path.join(BASELINE_DIR, 'login-status-shape.json');
+const PROMPTS_BASELINE = path.join(BASELINE_DIR, 'prompts-list.json');
+
+function jsonrpc(id, method, params) {
+  return JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
+}
+
+function normalizeSchema(s) {
+  if (!s || typeof s !== 'object') return s;
+  if (Array.isArray(s)) return s.map(normalizeSchema);
+  const out = {};
+  for (const k of Object.keys(s).sort()) {
+    out[k] = k === 'required' && Array.isArray(s[k]) ? [...s[k]].sort() : normalizeSchema(s[k]);
+  }
+  return out;
+}
+
+function shapeOnly(v) {
+  if (v === null || v === undefined) return v === null ? 'null' : 'undefined';
+  if (Array.isArray(v)) return v.length === 0 ? '[]' : ['<' + (typeof v[0] === 'object' ? 'object' : typeof v[0]) + '>'];
+  if (typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = shapeOnly(v[k]);
+    return out;
+  }
+  return typeof v;
+}
+
+function waitFor(fn, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const tick = () => {
+      if (fn()) return resolve();
+      if (Date.now() - start > timeoutMs) return reject(new Error(`timeout after ${timeoutMs}ms`));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+async function runSmoke() {
+  const creds = readCredentials() || {};
+  const childEnv = { ...process.env };
+  for (const k of ['LARK_COOKIE', 'LARK_APP_ID', 'LARK_APP_SECRET', 'LARK_USER_ACCESS_TOKEN', 'LARK_USER_REFRESH_TOKEN', 'LARK_PROFILES_JSON']) {
+    if (creds[k] && !childEnv[k]) childEnv[k] = creds[k];
+  }
+
+  const child = spawn('node', [SERVER_PATH], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: childEnv,
+  });
+
+  let buf = '';
+  const responses = new Map();
+  child.stdout.on('data', (d) => {
+    buf += d.toString();
+    const lines = buf.split('\n');
+    buf = lines.pop();
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id != null) responses.set(msg.id, msg);
+      } catch {}
+    }
+  });
+  child.stderr.on('data', () => {}); // discard
+
+  let exitErr = null;
+  child.on('exit', (code) => { if (code !== 0 && code !== null) exitErr = new Error(`server exited with code ${code}`); });
+
+  child.stdin.write(jsonrpc(1, 'initialize', {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'smoke', version: '0' },
+  }));
+  await waitFor(() => responses.has(1) || exitErr, 8000);
+  if (exitErr) throw exitErr;
+
+  child.stdin.write(jsonrpc(2, 'tools/list', {}));
+  await waitFor(() => responses.has(2) || exitErr, 8000);
+  if (exitErr) throw exitErr;
+
+  child.stdin.write(jsonrpc(3, 'tools/call', { name: 'get_login_status', arguments: {} }));
+  await waitFor(() => responses.has(3) || exitErr, 15000);
+  if (exitErr) throw exitErr;
+
+  child.stdin.write(jsonrpc(4, 'prompts/list', {}));
+  await waitFor(() => responses.has(4) || exitErr, 8000);
+  if (exitErr) throw exitErr;
+
+  child.kill('SIGTERM');
+
+  const tools = (responses.get(2)?.result?.tools || []).map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: normalizeSchema(t.inputSchema),
+  })).sort((a, b) => a.name.localeCompare(b.name));
+
+  let loginShape = null;
+  const txt = responses.get(3)?.result?.content?.[0]?.text;
+  if (typeof txt === 'string') {
+    try {
+      loginShape = shapeOnly(JSON.parse(txt));
+    } catch {
+      // Not JSON — capture as a plain text shape (length stays unstable so just record it's a string).
+      loginShape = { _format: 'text', _length_bucket: txt.length < 100 ? '<100' : txt.length < 1000 ? '<1000' : '>=1000' };
+    }
+  } else {
+    loginShape = { _error: 'no response', _raw: shapeOnly(responses.get(3)?.result) };
+  }
+
+  const prompts = (responses.get(4)?.result?.prompts || []).map((p) => ({
+    name: p.name,
+    description: p.description,
+    ...(p.arguments && p.arguments.length > 0 ? { arguments: p.arguments } : {}),
+  })).sort((a, b) => a.name.localeCompare(b.name));
+
+  return { tools, loginShape, prompts };
+}
+
+(async () => {
+  const cmd = process.argv[2] || 'dump';
+  let snap;
+  try {
+    snap = await runSmoke();
+  } catch (err) {
+    console.error('SMOKE FAIL:', err.message);
+    process.exit(1);
+  }
+
+  if (cmd === 'dump') {
+    process.stdout.write(JSON.stringify(snap, null, 2) + '\n');
+    return;
+  }
+  if (cmd === 'write-baseline') {
+    fs.mkdirSync(BASELINE_DIR, { recursive: true });
+    fs.writeFileSync(TOOLS_BASELINE, JSON.stringify(snap.tools, null, 2) + '\n');
+    fs.writeFileSync(LOGIN_BASELINE, JSON.stringify(snap.loginShape, null, 2) + '\n');
+    fs.writeFileSync(PROMPTS_BASELINE, JSON.stringify(snap.prompts, null, 2) + '\n');
+    console.error(`Baseline written: ${snap.tools.length} tools, ${snap.prompts.length} prompts, login_status shape captured`);
+    return;
+  }
+  if (cmd === 'diff') {
+    if (!fs.existsSync(TOOLS_BASELINE) || !fs.existsSync(LOGIN_BASELINE)) {
+      console.error('No baseline found. Run: node scripts/smoke.js write-baseline');
+      process.exit(2);
+    }
+    const expectedTools = JSON.parse(fs.readFileSync(TOOLS_BASELINE, 'utf8'));
+    const expectedLogin = JSON.parse(fs.readFileSync(LOGIN_BASELINE, 'utf8'));
+    const expectedPrompts = fs.existsSync(PROMPTS_BASELINE)
+      ? JSON.parse(fs.readFileSync(PROMPTS_BASELINE, 'utf8'))
+      : null;
+    const actualToolsStr = JSON.stringify(snap.tools, null, 2);
+    const expectedToolsStr = JSON.stringify(expectedTools, null, 2);
+    let ok = true;
+    if (actualToolsStr !== expectedToolsStr) {
+      ok = false;
+      const expectedNames = new Set(expectedTools.map(t => t.name));
+      const actualNames = new Set(snap.tools.map(t => t.name));
+      const added = [...actualNames].filter(n => !expectedNames.has(n));
+      const removed = [...expectedNames].filter(n => !actualNames.has(n));
+      console.error('TOOLS MISMATCH');
+      console.error(`expected ${expectedTools.length} tools, got ${snap.tools.length}`);
+      if (added.length) console.error(`  added:   ${added.join(', ')}`);
+      if (removed.length) console.error(`  removed: ${removed.join(', ')}`);
+      // Find tools whose schema/description changed
+      const expByName = Object.fromEntries(expectedTools.map(t => [t.name, t]));
+      const changed = snap.tools.filter(t => expByName[t.name] && JSON.stringify(t) !== JSON.stringify(expByName[t.name])).map(t => t.name);
+      if (changed.length) console.error(`  changed: ${changed.join(', ')}`);
+    }
+    if (JSON.stringify(snap.loginShape) !== JSON.stringify(expectedLogin)) {
+      ok = false;
+      console.error('LOGIN STATUS SHAPE MISMATCH');
+      console.error('expected:', JSON.stringify(expectedLogin, null, 2));
+      console.error('actual:  ', JSON.stringify(snap.loginShape, null, 2));
+    }
+    if (expectedPrompts !== null && JSON.stringify(snap.prompts, null, 2) !== JSON.stringify(expectedPrompts, null, 2)) {
+      ok = false;
+      const expectedNames = new Set(expectedPrompts.map(p => p.name));
+      const actualNames = new Set(snap.prompts.map(p => p.name));
+      const added = [...actualNames].filter(n => !expectedNames.has(n));
+      const removed = [...expectedNames].filter(n => !actualNames.has(n));
+      console.error('PROMPTS MISMATCH');
+      console.error(`expected ${expectedPrompts.length} prompts, got ${snap.prompts.length}`);
+      if (added.length) console.error(`  added:   ${added.join(', ')}`);
+      if (removed.length) console.error(`  removed: ${removed.join(', ')}`);
+      const expByName = Object.fromEntries(expectedPrompts.map(p => [p.name, p]));
+      const changed = snap.prompts.filter(p => expByName[p.name] && JSON.stringify(p) !== JSON.stringify(expByName[p.name])).map(p => p.name);
+      if (changed.length) console.error(`  changed: ${changed.join(', ')}`);
+    }
+    if (!ok) process.exit(1);
+    console.error(`OK: ${snap.tools.length} tools, ${snap.prompts.length} prompts, login_status shape matches`);
+    return;
+  }
+  console.error('usage: smoke.js [dump|diff|write-baseline]');
+  process.exit(2);
+})();

package/scripts/sync-claude-md.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -e
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+if git diff --cached --name-only | grep -qx "CLAUDE.md"; then
+  tail -n +2 CLAUDE.md > /tmp/feishu-claude-body.$$
+  { echo "# feishu-user-plugin — Codex Instructions"; cat /tmp/feishu-claude-body.$$; } > AGENTS.md
+  rm -f /tmp/feishu-claude-body.$$
+  cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md
+  git add AGENTS.md skills/feishu-user-plugin/references/CLAUDE.md
+  echo "[hook] CLAUDE.md → AGENTS.md + skill reference synced"
+fi

package/scripts/sync-server-json.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+'use strict';
+// Regenerates server.json so it never drifts from package.json + src/server.js.
+// Reads:
+//   - package.json: version, description (truncated to ~220 chars for display)
+//   - src/server.js TOOLS: tool list (name + description from inputSchema.description)
+// Preserves:
+//   - display_name, icon, repository, license, categories, tags,
+//     installations, environment_variables (these don't drift, edited by hand)
+// CI gate (validate.yml) re-runs this and diffs — drift = build fail.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const SERVER_JSON = path.join(ROOT, 'server.json');
+const PKG = require(path.join(ROOT, 'package.json'));
+const { TOOLS } = require(path.join(ROOT, 'src', 'server'));
+
+function deriveToolEntry(t) {
+  // Strip the "[Plugin]"/"[Cookie]"/etc category prefix from descriptions for compactness.
+  const desc = (t.description || '').replace(/^\[[^\]]+\]\s*/, '');
+  return { name: t.name, description: desc.split('\n')[0].slice(0, 200) };
+}
+
+const existing = JSON.parse(fs.readFileSync(SERVER_JSON, 'utf8'));
+
+// Truncate package.json description for the marketplace display field.
+// The package.json one is intentionally long for npm searches; server.json
+// trims it for cleaner cards.
+const shortDesc = PKG.description.replace(/\s+/g, ' ').slice(0, 220);
+
+const next = {
+  name: PKG.name,
+  display_name: existing.display_name || 'Feishu User Plugin for Claude Code',
+  description: shortDesc,
+  version: PKG.version,
+  icon: existing.icon || 'https://www.feishu.cn/favicon.ico',
+  repository: existing.repository || { type: 'git', url: PKG.repository?.url || '' },
+  license: existing.license || PKG.license || 'MIT',
+  categories: existing.categories || ['communication', 'messaging', 'productivity'],
+  tags: existing.tags || ['feishu', 'lark', 'im', 'messaging', 'docs', 'bitable', 'wiki', 'protobuf', 'plugin', 'claude-code'],
+  tools: TOOLS.map(deriveToolEntry),
+  installations: existing.installations || {
+    'claude-code': { type: 'stdio', command: 'npx', args: ['-y', 'feishu-user-plugin'] },
+  },
+  environment_variables: existing.environment_variables || [
+    { name: 'LARK_COOKIE',             description: 'Feishu web login cookie string (required for user identity messaging)', required: true },
+    { name: 'LARK_APP_ID',             description: 'Feishu Open Platform App ID (required for official API)',                required: true },
+    { name: 'LARK_APP_SECRET',         description: 'Feishu Open Platform App Secret (required for official API)',            required: true },
+    { name: 'LARK_USER_ACCESS_TOKEN',  description: 'OAuth user_access_token for P2P chat reading (run: npx feishu-user-plugin oauth)', required: true },
+    { name: 'LARK_USER_REFRESH_TOKEN', description: 'OAuth refresh_token for automatic UAT renewal (obtained via OAuth flow)', required: true },
+  ],
+};
+
+const cmd = process.argv[2] || 'write';
+const nextStr = JSON.stringify(next, null, 2) + '\n';
+
+if (cmd === 'check') {
+  const cur = fs.readFileSync(SERVER_JSON, 'utf8');
+  if (cur !== nextStr) {
+    console.error('ERROR: server.json is out of sync with package.json + src/server.js TOOLS.');
+    console.error('Fix: node scripts/sync-server-json.js');
+    process.exit(1);
+  }
+  console.log(`OK: server.json in sync (${TOOLS.length} tools, v${PKG.version})`);
+  process.exit(0);
+}
+
+fs.writeFileSync(SERVER_JSON, nextStr);
+console.log(`Regenerated server.json (${TOOLS.length} tools, v${PKG.version})`);

package/scripts/sync-team-skills.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -e
+TEAM_SKILLS="/Users/abble/team-skills/plugins/feishu-user-plugin"
+if [ ! -d "$TEAM_SKILLS" ]; then echo "[hook] team-skills not present, skip"; exit 0; fi
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+cp -r skills/. "$TEAM_SKILLS/skills/"
+cp .claude-plugin/plugin.json "$TEAM_SKILLS/.claude-plugin/"
+cd "$TEAM_SKILLS/.."
+VERSION=$(node -e "console.log(require('$TEAM_SKILLS/.claude-plugin/plugin.json').version)")
+BRANCH="sync/feishu-v$VERSION"
+if git rev-parse --verify "$BRANCH" >/dev/null 2>&1; then
+  echo "[hook] branch $BRANCH already exists, skipping"; exit 0
+fi
+git checkout -b "$BRANCH"
+git add "plugins/feishu-user-plugin/"
+git commit -m "chore: sync feishu-user-plugin v$VERSION skills + plugin.json" || { echo "[hook] nothing to sync"; exit 0; }
+git push -u origin "$BRANCH"
+gh pr create --title "Sync feishu-user-plugin v$VERSION" --body "Auto-sync from feishu-user-plugin main."
+PR_NUM=$(gh pr view --json number --jq .number)
+gh pr merge "$PR_NUM" --auto --merge
+echo "[hook] team-skills sync PR #$PR_NUM created with auto-merge"

package/scripts/test-all-tools.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// scripts/test-all-tools.js — semi-automated tool regression.
+//
+// Spawns the MCP server (src/index.js) as a stdio child, sends `initialize` +
+// `tools/list`, then calls a curated set of READ tools to verify each domain
+// is wired up. Writes a per-tool pass/fail summary to stdout.
+//
+// Read-only by design: this script does NOT create / modify / delete any
+// Feishu resources. For write-tool regression, see docs/TESTING-METHODOLOGY.md
+// "Live regression checklist".
+//
+// Usage:
+//   node scripts/test-all-tools.js
+//   node scripts/test-all-tools.js --user-id <open_id>   # to also test list_user_okrs
+//   node scripts/test-all-tools.js --json                # machine-readable output
+//
+// Exit code: 0 if all calls succeed, 1 if any failed.
+
+const { spawn } = require('child_process');
+const path = require('path');
+const { readCredentials } = require('../src/config');
+
+const SERVER_PATH = path.join(__dirname, '..', 'src', 'index.js');
+
+function jsonrpc(id, method, params) {
+  return JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
+}
+
+function waitFor(fn, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const tick = () => {
+      if (fn()) return resolve();
+      if (Date.now() - start > timeoutMs) return reject(new Error(`timeout after ${timeoutMs}ms`));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+async function runRegression() {
+  const cliArgs = process.argv.slice(2);
+  const wantJson = cliArgs.includes('--json');
+  const userIdIdx = cliArgs.indexOf('--user-id');
+  const userId = userIdIdx >= 0 ? cliArgs[userIdIdx + 1] : null;
+
+  const creds = readCredentials() || {};
+  const childEnv = { ...process.env };
+  for (const k of ['LARK_COOKIE', 'LARK_APP_ID', 'LARK_APP_SECRET', 'LARK_USER_ACCESS_TOKEN', 'LARK_USER_REFRESH_TOKEN', 'LARK_PROFILES_JSON']) {
+    if (creds[k] && !childEnv[k]) childEnv[k] = creds[k];
+  }
+
+  const child = spawn('node', [SERVER_PATH], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: childEnv,
+  });
+  let buf = '';
+  const responses = new Map();
+  child.stdout.on('data', (d) => {
+    buf += d.toString();
+    const lines = buf.split('\n');
+    buf = lines.pop();
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id != null) responses.set(msg.id, msg);
+      } catch {}
+    }
+  });
+  child.stderr.on('data', () => {});
+
+  let nextId = 1;
+  function call(method, params, timeoutMs = 15000) {
+    const id = nextId++;
+    child.stdin.write(jsonrpc(id, method, params));
+    return waitFor(() => responses.has(id), timeoutMs).then(() => responses.get(id));
+  }
+
+  const init = await call('initialize', {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'test-all-tools', version: '0' },
+  });
+  if (init.error) throw new Error(`initialize failed: ${JSON.stringify(init.error)}`);
+
+  const toolsResp = await call('tools/list', {});
+  const allTools = (toolsResp.result?.tools || []).map((t) => t.name).sort();
+
+  // Curated read-only suite. Each entry: [name, args, optional notes].
+  const SUITE = [
+    ['get_login_status', {}],
+    ['list_profiles', {}],
+    ['list_chats', { page_size: 5 }],
+    ['search_contacts', { query: 'feishu' }],
+    ['list_calendars', { page_size: 50 }],
+    ['list_okr_periods', {}],
+    ['list_wiki_spaces', {}],
+    ['search_docs', { query: 'README' }],
+    ['list_files', {}],
+  ];
+  if (userId) SUITE.push(['list_user_okrs', { user_id: userId, limit: 1 }]);
+  // list_tasks (v1.3.7) is safe but only meaningful if Tasks scope is granted.
+  if (allTools.includes('list_tasks')) SUITE.push(['list_tasks', { page_size: 1 }]);
+
+  const results = [];
+  for (const [name, args] of SUITE) {
+    if (!allTools.includes(name)) {
+      results.push({ tool: name, ok: false, skipped: true, reason: 'tool not registered' });
+      continue;
+    }
+    const t0 = Date.now();
+    try {
+      const r = await call('tools/call', { name, arguments: args }, 30000);
+      const ms = Date.now() - t0;
+      if (r.error) {
+        results.push({ tool: name, ok: false, ms, error: r.error.message });
+      } else {
+        const isError = r.result?.isError === true;
+        results.push({ tool: name, ok: !isError, ms, summary: summarize(r.result) });
+      }
+    } catch (e) {
+      results.push({ tool: name, ok: false, ms: Date.now() - t0, error: e.message });
+    }
+  }
+
+  child.kill('SIGTERM');
+
+  if (wantJson) {
+    process.stdout.write(JSON.stringify({ allTools: allTools.length, results }, null, 2) + '\n');
+  } else {
+    const okCount = results.filter((r) => r.ok).length;
+    const failCount = results.filter((r) => !r.ok && !r.skipped).length;
+    const skipCount = results.filter((r) => r.skipped).length;
+    console.log(`Tool registry size: ${allTools.length}`);
+    console.log(`Suite: ${okCount} ok, ${failCount} fail, ${skipCount} skipped (out of ${results.length} planned)\n`);
+    for (const r of results) {
+      const status = r.skipped ? 'SKIP' : (r.ok ? ' OK ' : 'FAIL');
+      const ms = r.ms !== undefined ? ` ${r.ms}ms` : '';
+      const tail = r.error ? ` — ${r.error}` : (r.reason ? ` — ${r.reason}` : (r.summary ? ` — ${r.summary}` : ''));
+      console.log(`  [${status}]${ms.padStart(8)} ${r.tool}${tail}`);
+    }
+    if (failCount > 0) process.exit(1);
+  }
+}
+
+function summarize(result) {
+  const txt = result?.content?.[0]?.text;
+  if (!txt) return '';
+  // Crop multi-line summaries to the first line + length.
+  const firstLine = txt.split('\n', 1)[0];
+  return firstLine.length > 80 ? firstLine.slice(0, 77) + '…' : firstLine;
+}
+
+runRegression().catch((e) => {
+  console.error('Regression failed:', e.message);
+  process.exit(2);
+});

package/scripts/test-wiki-attach-fallback.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+'use strict';
+// Simulates wiki:wiki scope insufficient and verifies the upload fallback path
+// surfaces a clear error rather than burying the wiki failure under a generic
+// "uploaded to drive root, attach failed" silent miss.
+//
+// Approach: monkey-patch attachToWiki on the LarkOfficialClient prototype to
+// throw a 91403 (the production wiki "no permission" code), then call
+// upload_drive_file with wiki_space_id and check the response.
+
+const { readCredentials } = require('../src/auth/credentials');
+const creds = readCredentials();
+if (!creds.LARK_APP_ID || !creds.LARK_APP_SECRET || !creds.LARK_USER_ACCESS_TOKEN) {
+  console.error('Skipped: needs LARK_APP_ID / LARK_APP_SECRET / UAT (skip on CI).');
+  process.exit(77); // POSIX skip code
+}
+
+(async () => {
+  const { LarkOfficialClient } = require('../src/clients/official');
+  const client = new LarkOfficialClient(creds.LARK_APP_ID, creds.LARK_APP_SECRET);
+  client.loadUAT();
+
+  const original = client.attachToWiki?.bind(client);
+  if (!original) { console.error('attachToWiki not present — wiki domain may not be loaded.'); process.exit(2); }
+
+  client.attachToWiki = async function(...args) {
+    const err = new Error('attachToWiki failed (HTTP 403, code=91403): wiki scope not granted');
+    err.code = 91403;
+    throw err;
+  };
+
+  const tmpFile = '/tmp/feishu-test-attach-fallback.txt';
+  require('fs').writeFileSync(tmpFile, 'attach-fallback-test ' + Date.now());
+
+  // Need a real folder_token: this script is opportunistic — pass via env
+  // FEISHU_TEST_FOLDER_TOKEN. Skip cleanly otherwise.
+  const folderToken = process.env.FEISHU_TEST_FOLDER_TOKEN;
+  if (!folderToken) {
+    console.error('Skipped: set FEISHU_TEST_FOLDER_TOKEN env (a real Drive folder token you can write to) to exercise this fallback.');
+    require('fs').unlinkSync(tmpFile);
+    process.exit(77);
+  }
+
+  try {
+    const res = await client.uploadDriveFile({
+      file_path: tmpFile,
+      file_name: 'attach-fallback-test.txt',
+      folder_token: folderToken,
+      parent_type: 'explorer',
+      wiki_space_id: '0000000000000000', // bogus; attachToWiki monkey-patch throws 91403 either way
+    });
+    console.log('Result:', JSON.stringify(res, null, 2));
+    if (res?._wikiAttachWarning || res?.error || /91403|wiki/i.test(JSON.stringify(res))) {
+      console.log('PASS: upload surfaces the wiki attach failure');
+      process.exit(0);
+    }
+    console.log('FAIL: upload did not surface the wiki attach failure');
+    process.exit(1);
+  } catch (e) {
+    // The monkey-patched attachToWiki throws — uploadDriveFile may rethrow.
+    // That's also acceptable as long as the message preserves the wiki failure.
+    if (/91403|wiki/i.test(e.message)) {
+      console.log('PASS: upload surfaces the wiki attach failure via thrown error:', e.message);
+      process.exit(0);
+    }
+    console.error('FAIL: upload threw, but message does not mention wiki/91403:', e.message);
+    process.exit(1);
+  } finally {
+    try { require('fs').unlinkSync(tmpFile); } catch {}
+  }
+})().catch((e) => { console.error('Error:', e.message); process.exit(1); });