feishu-docs-cli 0.1.0-beta.9 → 1.0.1

package/dist/utils/scope-prompt.js

@@ -1,24 +1,21 @@
 /**
- * Interactive scope authorization prompt and recovery utilities.
+ * Reactive scope authorization: prompt and recovery utilities.
  *
- * When a command discovers missing OAuth scopes, these helpers guide
- * the user through authorizing them — or gracefully skipping if the
- * user declines (or the session is non-interactive).
+ * Instead of pre-flight scope checks, this module provides:
+ *
+ * - `promptScopeAuth()` — Interactive OAuth prompt for missing scopes.
+ * - `withScopeRecovery()` — Wrapper that catches SCOPE_MISSING errors,
+ *   prompts the user (if interactive), and retries the operation once.
+ *
+ * The Feishu API is the source of truth for required scopes. When an API
+ * call fails with 99991672 (app scope) or 99991679 (user scope), `fetchWithAuth`
+ * throws `CliError("SCOPE_MISSING", { missingScopes })`. This module handles
+ * the recovery.
  */
 import * as readline from "node:readline";
 import { oauthLogin, loadTokens } from "../auth.js";
-import { createClient } from "../client.js";
 import { CliError } from "./errors.js";
-import { BASE_SCOPES, mergeScopes, getMissingScopes, buildScopeHint, } from "../scopes.js";
-/**
- * Check whether an error is a permission / scope error.
- */
-export function isPermissionError(err) {
-    if (err instanceof CliError) {
-        return (err.errorType === "PERMISSION_DENIED" || err.errorType === "AUTH_REQUIRED");
-    }
-    return false;
-}
+import { BASE_SCOPES, mergeScopes, buildScopeHint } from "../scopes.js";
 /**
  * Ask a yes/no question on stderr, read from stdin.
  * Returns true only if user answers "y" or "yes".
@@ -44,11 +41,8 @@ function askYesNo(question) {
  *
  * Returns `true` if authorization succeeded, `false` otherwise.
  * Always returns `false` in non-interactive contexts (JSON mode, non-TTY).
- *
- * @param storedScopeStr  Pre-loaded stored scope string (avoids duplicate
- *                        loadTokens call when called from ensureScopes).
  */
-export async function promptScopeAuth(missingScopes, globalOpts, storedScopeStr) {
+export async function promptScopeAuth(missingScopes, globalOpts) {
     // Non-interactive: skip prompt
     if (globalOpts.json || !process.stdin.isTTY) {
         return false;
@@ -57,6 +51,10 @@ export async function promptScopeAuth(missingScopes, globalOpts, storedScopeStr)
     const appSecret = process.env.FEISHU_APP_SECRET;
     if (!appId || !appSecret)
         return false;
+    // Skip interactive OAuth when using env-var token — re-auth would save to file
+    // but createClient still prefers the env token, so retry would fail again.
+    if (process.env.FEISHU_USER_TOKEN)
+        return false;
     const scopeList = missingScopes.join(", ");
     const scopeStr = missingScopes.join(" ");
     process.stderr.write(`\nfeishu-docs: 缺少以下权限: ${scopeList}\n` +
@@ -67,16 +65,10 @@ export async function promptScopeAuth(missingScopes, globalOpts, storedScopeStr)
     if (!yes)
         return false;
     // Merge missing scopes with current grants and re-run OAuth
-    let currentScopes;
-    if (storedScopeStr) {
-        currentScopes = storedScopeStr.split(/\s+/).filter(Boolean);
-    }
-    else {
-        const stored = await loadTokens();
-        currentScopes = stored?.tokens?.scope
-            ? stored.tokens.scope.split(/\s+/).filter(Boolean)
-            : [...BASE_SCOPES];
-    }
+    const stored = await loadTokens();
+    const currentScopes = stored?.tokens?.scope
+        ? stored.tokens.scope.split(/\s+/).filter(Boolean)
+        : [...BASE_SCOPES];
     const merged = mergeScopes(currentScopes, missingScopes);
     try {
         await oauthLogin(appId, {
@@ -94,30 +86,49 @@ export async function promptScopeAuth(missingScopes, globalOpts, storedScopeStr)
     }
 }
 /**
- * Pre-flight scope check with interactive recovery.
+ * Wrap an async operation with reactive scope error recovery.
+ *
+ * When the operation throws `CliError("SCOPE_MISSING")`:
+ * - If interactive (TTY + non-JSON) and scopes are known: prompt → retry once.
+ * - Otherwise: re-throw with a clear recovery hint.
  *
- * If scopes are missing and the user authorizes them, returns a fresh
- * `AuthInfo` with the new token. If no recovery is needed, returns the
- * original `authInfo` unchanged. If the user declines, throws.
+ * @param fallbackScopes  Scope names to use when the API doesn't include
+ *   `permission_violations` (older APIs like search). When the error has
+ *   empty `missingScopes` but `fallbackScopes` is provided, these are used
+ *   for the authorization prompt.
  */
-export async function ensureScopes(authInfo, requiredScopes, globalOpts) {
-    if (authInfo.mode !== "user")
-        return authInfo;
-    // No stored file → env-var token or tenant mode; scope info unavailable,
-    // skip pre-flight check (downstream API call will surface permission errors).
-    const stored = await loadTokens();
-    if (!stored)
-        return authInfo;
-    const missing = getMissingScopes(stored.tokens.scope, [...requiredScopes]);
-    if (missing.length === 0)
-        return authInfo;
-    // Pass stored scope string to avoid a second loadTokens() call
-    const authorized = await promptScopeAuth(missing, globalOpts, stored.tokens.scope);
-    if (!authorized) {
-        throw new CliError("AUTH_REQUIRED", buildScopeHint(missing));
+export async function withScopeRecovery(fn, globalOpts, fallbackScopes) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (!(err instanceof CliError) || err.errorType !== "SCOPE_MISSING") {
+            throw err;
+        }
+        const apiScopes = err.missingScopes ?? [];
+        const scopes = apiScopes.length > 0 ? apiScopes : (fallbackScopes ?? []);
+        // No scopes from API or fallback → can't prompt meaningfully, just throw
+        if (scopes.length === 0) {
+            throw err;
+        }
+        // Tenant mode: OAuth produces a user token which tenant auth ignores,
+        // so interactive recovery would be pointless — just throw with a hint.
+        if (globalOpts.auth === "tenant") {
+            throw new CliError("AUTH_REQUIRED", buildScopeHint(scopes), {
+                apiCode: err.apiCode,
+                missingScopes: scopes,
+            });
+        }
+        // Try interactive recovery
+        const authorized = await promptScopeAuth(scopes, globalOpts);
+        if (!authorized) {
+            throw new CliError("AUTH_REQUIRED", buildScopeHint(scopes), {
+                apiCode: err.apiCode,
+                missingScopes: scopes,
+            });
+        }
+        // Retry once — if it fails again, let the error propagate
+        return await fn();
     }
-    // Re-create client to pick up the fresh token
-    const { authInfo: refreshed } = await createClient(globalOpts);
-    return refreshed;
 }
 //# sourceMappingURL=scope-prompt.js.map

package/dist/utils/scope-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"scope-prompt.js","sourceRoot":"","sources":["../../src/utils/scope-prompt.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scope-prompt.js","sourceRoot":"","sources":["../../src/utils/scope-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGxE;;;GAGG;AACH,SAAS,QAAQ,CAAC,QAAgB;IAChC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC;YAClC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QACH,EAAE,CAAC,QAAQ,CAAC,GAAG,QAAQ,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE;YAC3C,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,aAAuB,EACvB,UAAsB;IAEtB,+BAA+B;IAC/B,IAAI,UAAU,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IACxC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAChD,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAEvC,+EAA+E;IAC/E,2EAA2E;IAC3E,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAAE,OAAO,KAAK,CAAC;IAEhD,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0BAA0B,SAAS,IAAI;QACrC,gEAAgE;QAChE,8CAA8C;QAC9C,0CAA0C,QAAQ,OAAO,CAC5D,CAAC;IAEF,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC1C,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IAEvB,4DAA4D;IAC5D,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,MAAM,aAAa,GAAG,MAAM,EAAE,MAAM,EAAE,KAAK;QACzC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QAClD,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;IACrB,MAAM,MAAM,GAAG,WAAW,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IAEzD,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,KAAK,EAAE;YACtB,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;YACvB,SAAS;YACT,OAAO,EAAE,UAAU,CAAC,IAAI;SACzB,CAAC,CAAC;QACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,MAAM,MAAM,CAAC,CAAC;QACzD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAoB,EACpB,UAAsB,EACtB,cAAyB;IAEzB,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,CAAC,GAAG,YAAY,QAAQ,CAAC,IAAI,GAAG,CAAC,SAAS,KAAK,eAAe,EAAE,CAAC;YACpE,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,MAAM,SAAS,GAAG,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;QAEzE,yEAAyE;QACzE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,sEAAsE;QACtE,uEAAuE;QACvE,IAAI,UAAU,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE;gBAC1D,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,aAAa,EAAE,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAED,2BAA2B;QAC3B,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QAC7D,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE;gBAC1D,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,aAAa,EAAE,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAED,0DAA0D;QAC1D,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feishu-docs-cli",
-  "version": "0.1.0-beta.9",
+  "version": "1.0.1",
   "description": "CLI tool for AI Agents to read/write Feishu docs via shell commands",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "build:check": "tsc --noEmit",
     "pretest": "npm run build:check",
     "test": "tsx --test test/*.test.ts",
+    "lint:dead-code": "knip",
     "prepublishOnly": "npm run build"
   },
   "repository": {
@@ -47,6 +48,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "knip": "^6.0.6",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }

package/skills/feishu-docs/SKILL.md

@@ -9,7 +9,23 @@ description: Read, write, search, and manage Feishu (Lark) cloud documents and k
 
 ## Prerequisites
 
-Before using any command, verify the environment is ready:
+Before using any command, check that the CLI is installed and authenticated. Run these two checks in order:
+
+### Step 1: Check installation
+
+```bash
+command -v feishu-docs >/dev/null 2>&1 && feishu-docs --version || echo "NOT_INSTALLED"
+```
+
+If the output is `NOT_INSTALLED`, install the CLI first:
+
+```bash
+npm install -g feishu-docs-cli
+```
+
+This installs the `feishu-docs` command globally. Requires Node.js 18+. After installation, verify with `feishu-docs --version`.
+
+### Step 2: Check authentication
 
 ```bash
 feishu-docs whoami
@@ -90,7 +106,7 @@ feishu-docs update <url> --body ./extra.md --append
 echo "## New Section" | feishu-docs update <url> --body - --append
 ```
 
-Overwrite mode automatically backs up the current document to `~/.feishu-docs/backups/` before writing. If the write fails, it auto-recovers from the backup.
+Overwrite mode automatically backs up the current document to `~/.feishu-docs/backups/` before writing. If the write fails, it auto-recovers from the backup. Backups are kept for undo; old backups are rotated automatically (max 10 per document).
 
 To restore a previous version:
 ```bash
@@ -170,6 +186,7 @@ Every command accepts these flags:
 | `--auth tenant` | Force app token (CI/CD, shared docs) |
 | `--json` | Output structured JSON instead of text |
 | `--lark` | Use Lark (international) domain |
+| `-v, --version` | Show version number |
 
 Default auth mode is `auto` — tries user token first, falls back to tenant.
 
@@ -189,6 +206,10 @@ Default auth mode is `auto` — tries user token first, falls back to tenant.
 
 - Only `docx` (new document format) is fully supported for read/write
 - Legacy `doc` format is not supported
-- Images cannot be written; read returns temporary URLs valid ~24 hours
+- Embedded `sheet` and `bitable` are rendered as tables (lossy)
+- Embedded `board`/`whiteboard` are exported as local PNG images
+- `mindnote` renders as a link only
+- Images are downloaded to `~/.feishu-docs/images/` with 30-day cache. Image write is not supported.
+- Mermaid code blocks are preserved as-is (code block, not visual diagram) — the Open API does not support creating visual "text diagram" blocks
 - Markdown conversion is lossy — use `--blocks` for lossless JSON when precision matters
 - Search requires user-level auth (run `feishu-docs login` first)