fanfou 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leaking
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# 饭否 CLI (`fanfou`)
+
+An **LLM-friendly** command line for the [Fanfou (饭否)](https://fanfou.com) API,
+plus a bundled **agent skill** that works with Claude Code, Codex, Cursor, and
+50+ other AI coding agents. JSON-by-default output, schema introspection,
+dry-run previews, and a three-layer command surface (shortcuts / resource
+commands / raw API).
+
+## Requirements
+
+- Node.js **≥ 22.6** (the CLI runs TypeScript directly via type-stripping — no build step needed).
+
+## Install
+
+```bash
+# 1) The CLI (provides the `fanfou` command):
+npm install -g fanfou          # or one-off, no install: npx fanfou <command>
+
+# 2) The skill, into your AI agent(s) — via npx skills (GitHub as registry):
+npx skills add Leaking/fanfou-cli -y -g
+#    …or target specific agents (Claude Code, Codex, Cursor, 50+ more):
+npx skills add Leaking/fanfou-cli --agent claude-code codex cursor
+```
+
+Run it:
+
+```bash
+fanfou --help
+```
+
+Developing from a clone (Node ≥ 22.6 runs the TypeScript directly — no build):
+
+```bash
+node src/index.ts --help
+```
+
+## Quick start
+
+```bash
+# 1) Log in (XAuth). Use env vars to keep secrets out of argv.
+FANFOU_USERNAME='you@example.com' FANFOU_PASSWORD='••••••' fanfou auth login
+
+# 2) Read your timeline
+fanfou +timeline --count 10
+fanfou +timeline --format table
+
+# 3) Post / reply / repost
+fanfou +post "Hello 饭否"
+fanfou +reply <status-id> "说得对"
+fanfou +repost <status-id>
+
+# 4) Anything else, raw:
+fanfou api GET statuses/mentions.json --query count=5
+```
+
+## Three layers
+
+1. **Shortcuts** (`+timeline`, `+post`, `+reply`, `+repost`, `+mentions`, `+me`,
+   `+search`, `+fav`, `+dm`) — high-frequency operations with smart defaults.
+2. **Resource commands** — `auth`, `timeline`, `status`, `favorite`, `user`,
+   `friendship`, `dm`, `account`, `search` (full Fanfou API coverage).
+3. **Raw API** — `fanfou api <GET|POST> <path> [--query ...] [--form ...]`.
+
+## Authentication
+
+Two flows, stored per-profile under `~/.config/fanfou/config.json` (mode `0600`):
+
+- **XAuth** (default): `fanfou auth login -u <name> -p <pass>`
+- **OAuth web**: `fanfou auth oauth-url` → approve in browser →
+  `fanfou auth oauth-exchange --token … --secret … [--verifier …]`
+
+Env overrides (handy for CI / agents): `FANFOU_USERNAME`, `FANFOU_PASSWORD`,
+`FANFOU_OAUTH_TOKEN`, `FANFOU_OAUTH_TOKEN_SECRET`, `FANFOU_CONSUMER_KEY`,
+`FANFOU_CONSUMER_SECRET`, `FANFOU_PROFILE`, `FANFOU_CONFIG_DIR`.
+
+Multiple accounts: pass `--profile <name>` to any command, or
+`fanfou auth use <name>` to change the default.
+
+## LLM / agent friendliness
+
+- **JSON by default** on stdout; errors are JSON on stderr with exit codes
+  (`2` usage, `3` auth-required, `1` other/HTTP).
+- **Schema introspection**: `fanfou <cmd> --help --format json`.
+- **Dry-run** (`--dry-run` / `-n`) on every state-changing command prints the
+  exact signed request without sending it.
+- **Output formats**: `--format json|ndjson|table|raw` (`-o`).
+- Robust arg parsing for Fanfou IDs that begin with `-`.
+
+## The bundled agent skill
+
+A single, cross-agent skill lives at
+[`skills/fanfou/SKILL.md`](skills/fanfou/SKILL.md). It is consumable by any
+AI coding agent that supports the [skills](https://github.com/vercel-labs/skills)
+convention — Claude Code, Codex, Cursor, Cline, Aider, Continue, and 50+ more.
+
+Install it globally for all of your agents at once, or scope it to a specific
+agent:
+
+```bash
+npx skills add Leaking/fanfou-cli -y -g                           # all agents
+npx skills add Leaking/fanfou-cli --agent claude-code codex cursor # specific
+```
+
+From a local clone, you can also drop the skill into a Claude Code skills
+directory directly (other agents typically use the `skills` CLI above):
+
+```bash
+npm run install-skill           # -> ./.claude/skills/fanfou (project)
+npm run install-skill -- --user # -> ~/.claude/skills/fanfou (global)
+```
+
+## Develop
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # node --test (OAuth1 signer vectors)
+npm run build       # emit dist/
+```
+
+The OAuth1 HMAC-SHA1 signer matches the canonical RFC 5849 example signature
+(pinned by `test/oauth1.test.ts`). Fanfou signs the base string over `http://`
+even on HTTPS requests — the signer replicates that quirk.

package/dist/args.js

@@ -0,0 +1,91 @@
+const SHORT_ALIASES = {
+    h: "help",
+    o: "format",
+    n: "dry-run",
+    v: "verbose",
+    q: "quiet",
+};
+/**
+ * Minimal, predictable argument parser.
+ * - `--key=value` and `--key value` both bind a value.
+ * - `--flag` is boolean true when its name is in `booleanFlags` or no value follows.
+ * - `+shortcut` and other bare tokens are positionals.
+ * - `--` stops flag parsing; everything after is positional.
+ */
+export function parseArgs(argv, booleanFlags) {
+    const positionals = [];
+    const flags = new Map();
+    let onlyPositionals = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (onlyPositionals) {
+            positionals.push(token);
+            continue;
+        }
+        if (token === "--") {
+            onlyPositionals = true;
+            continue;
+        }
+        if (token.startsWith("--")) {
+            const body = token.slice(2);
+            const eq = body.indexOf("=");
+            if (eq >= 0) {
+                flags.set(body.slice(0, eq), body.slice(eq + 1));
+                continue;
+            }
+            const name = body;
+            if (booleanFlags.has(name)) {
+                flags.set(name, true);
+                continue;
+            }
+            const next = argv[i + 1];
+            if (next !== undefined && !(next.startsWith("--") || next === "-")) {
+                flags.set(name, next);
+                i++;
+            }
+            else {
+                flags.set(name, true);
+            }
+            continue;
+        }
+        // Only treat an exact single-letter known short (e.g. -h, -u, -o) as a flag.
+        // Anything else starting with "-" is a positional — Fanfou ids often begin
+        // with "-" (e.g. -A_ycI00_Kc), so we must not misread them as flags.
+        const short = token.slice(1);
+        if (token.startsWith("-") && short.length === 1 && short in SHORT_ALIASES) {
+            const long = SHORT_ALIASES[short];
+            if (booleanFlags.has(long)) {
+                flags.set(long, true);
+            }
+            else {
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith("-")) {
+                    flags.set(long, next);
+                    i++;
+                }
+                else {
+                    flags.set(long, true);
+                }
+            }
+            continue;
+        }
+        positionals.push(token);
+    }
+    return { positionals, flags };
+}
+export function flagString(flags, name) {
+    const value = flags.get(name);
+    if (value === undefined)
+        return undefined;
+    return typeof value === "string" ? value : "";
+}
+export function flagBool(flags, name) {
+    return flags.has(name) && flags.get(name) !== "false";
+}
+export function flagNumber(flags, name) {
+    const value = flagString(flags, name);
+    if (value === undefined || value === "")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}