frigatebird 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.2.0 - 2026-02-08
+
+### Added
+- Modular architecture split across `cli`, `commands`, `client`, `browser`, and `lib` domains.
+- Expanded bird-compatible CLI surface including timeline/search/news/lists/follows/likes/bookmarks/about/query commands.
+- Integrated `x-list-manager` workflows: `refresh`, `add`, `remove`, and `batch`.
+- Config and environment precedence matching bird semantics.
+- Media attachment validation parity (`--media`, `--alt`, max counts, video constraints).
+- Deterministic read-only end-to-end tests using local fixture pages and `--base-url`.
+- Project skill files: `SKILL.md`, `SPEC.md`, `TASKS.md`.
+
+### Changed
+- Runtime engine standardized on Playwright browser automation instead of GraphQL internals.
+- `query-ids` retained as a compatibility command in Playwright mode.
+- Documentation now explicitly describes Frigatebird intent and contrast with bird.
+
+### Tests
+- Added broad unit coverage across option parsing, invocation normalization, handlers, and Playwright client behavior.
+- Added read-only empty-account e2e coverage for command stability in low-data scenarios.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean McLellan
+
+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,186 @@
+# frigatebird
+
+`frigatebird` is a Playwright-first X CLI that targets `bird` command parity and pulls in `x-list-manager` list automation.
+
+It keeps the `bird` UX, but replaces deprecated/non-open GraphQL internals with browser automation against X web UI.
+
+## Intent
+
+Frigatebird exists to keep the `bird` workflow alive after deprecation and closure:
+
+- Preserve familiar command ergonomics from `bird`.
+- Keep zero-API-key operation via local browser session cookies.
+- Add first-class list management from `x-list-manager` (`add`, `remove`, `batch`, `refresh`).
+- Provide one CLI for read workflows, account actions, and list operations.
+
+## Frigatebird vs Bird
+
+| Area | `bird` | `frigatebird` |
+|---|---|---|
+| Primary engine | X internal GraphQL + query IDs | Playwright web automation |
+| API keys | Not required | Not required |
+| Auth | Browser cookies / env tokens | Browser cookies / env tokens |
+| `query-ids` | Active GraphQL cache/refresh behavior | Compatibility command in Playwright mode |
+| List manager commands | External project (`x-list-manager`) | Built in (`refresh`, `add`, `remove`, `batch`) |
+| Selector/query fragility | Query ID churn | DOM selector churn |
+
+## Install
+
+```bash
+npm install
+npx playwright install chromium
+```
+
+## Usage
+
+```bash
+# One-off
+npx tsx src/cli.ts whoami
+
+# Built binary
+npm run build
+node dist/cli.js --help
+```
+
+## Commands
+
+### bird-style parity commands
+
+- `tweet <text>`
+- `post <text>`
+- `reply <tweet-id-or-url> <text>`
+- `read <tweet-id-or-url> [--json] [--json-full]`
+- `replies <tweet-id-or-url> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
+- `thread <tweet-id-or-url> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
+- `search <query> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
+- `mentions [-u @handle] [-n count] [--json] [--json-full]`
+- `user-tweets <@handle> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
+- `home [-n count] [--following] [--all] [--max-pages n] [--delay ms] [--json] [--json-full]`
+- `bookmarks [-n count] [--folder-id id] [--all] [--max-pages n] [--cursor str] [--expand-root-only] [--author-chain] [--author-only] [--full-chain-only] [--include-ancestor-branches] [--include-parent] [--thread-meta] [--sort-chronological] [--delay ms] [--json] [--json-full]`
+- `unbookmark <tweet-id-or-url...> [--json]`
+- `like <tweet-id-or-url>`
+- `retweet <tweet-id-or-url>`
+- `likes [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
+- `follow <username-or-id>`
+- `unfollow <username-or-id>`
+- `following [--user userId] [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
+- `followers [--user userId] [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
+- `lists [--member-of] [-n count] [--json] [--json-full]`
+- `list` (alias for `lists`)
+- `list-timeline <list-id-or-url> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
+- `news [-n count] [--ai-only] [--with-tweets] [--tweets-per-item n] [--for-you] [--news-only] [--sports] [--entertainment] [--trending-only] [--json] [--json-full]`
+- `trending` (alias for `news`)
+- `about <@handle> [--json]`
+- `query-ids [--fresh] [--json]` (compatibility mode in Playwright engine)
+- `whoami [--json]`
+- `check`
+- `help [command]`
+
+### x-list-manager parity commands
+
+- `refresh [--json]`
+- `add <listName> <handles...> [--no-headless] [--json]`
+- `remove <handle> <listName> [--no-headless] [--json]`
+- `batch <file.json> [--no-headless] [--json]`
+
+## Global Options
+
+- `--auth-token <token>`
+- `--ct0 <token>`
+- `--base-url <url>` (testing override, default `https://x.com`)
+- `--cookie-source <chrome|firefox|safari|edge>` (repeatable)
+- `--chrome-profile <name>`
+- `--chrome-profile-dir <path>`
+- `--firefox-profile <name>`
+- `--cookie-timeout <ms>`
+- `--timeout <ms>`
+- `--quote-depth <n>`
+- `--media <path>` (repeatable)
+- `--alt <text>` (repeatable)
+- `--plain`
+- `--no-emoji`
+- `--no-color`
+- `--no-headless`
+
+`tweet` and `reply` both consume `--media`/`--alt`.
+
+Media constraints:
+- up to 4 attachments
+- only one video
+- video cannot be mixed with other media
+- supported extensions: `jpg`, `jpeg`, `png`, `webp`, `gif`, `mp4`, `m4v`, `mov`
+
+## Config + Env
+
+Precedence: **CLI flags > env vars > project config > global config**.
+
+Config files:
+- Global (bird): `~/.config/bird/config.json5`
+- Global (frigatebird): `~/.config/frigatebird/config.json5`
+- Project (bird): `./.birdrc.json5`
+- Project (frigatebird): `./.frigatebirdrc.json5`
+
+Supported config keys:
+- `authToken`, `ct0`, `baseUrl`
+- `cookieSource`
+- `chromeProfile`, `chromeProfileDir`, `firefoxProfile`
+- `cookieTimeoutMs`, `timeoutMs`, `quoteDepth`
+
+Supported env vars:
+- Auth: `AUTH_TOKEN`, `CT0`, `TWITTER_AUTH_TOKEN`, `TWITTER_CT0`
+- Cookie source: `BIRD_COOKIE_SOURCE`, `FRIGATEBIRD_COOKIE_SOURCE`
+- Base URL: `BIRD_BASE_URL`, `FRIGATEBIRD_BASE_URL`
+- Profiles: `BIRD_CHROME_PROFILE`, `BIRD_CHROME_PROFILE_DIR`, `BIRD_FIREFOX_PROFILE` (plus `FRIGATEBIRD_*` variants)
+- Timeouts/depth: `BIRD_TIMEOUT_MS`, `BIRD_COOKIE_TIMEOUT_MS`, `BIRD_QUOTE_DEPTH` (plus `FRIGATEBIRD_*` variants)
+- Output: `NO_COLOR`, `BIRD_PLAIN`, `FRIGATEBIRD_PLAIN`
+
+## Shorthand Invocation
+
+If first argument is a tweet URL or ID, Frigatebird rewrites to `read`:
+
+```bash
+npx tsx src/cli.ts 1891234567890123456 --json
+```
+
+## Architecture
+
+- `src/cli/`: commander program assembly and global option wiring
+- `src/commands/`: handler layer and output orchestration
+- `src/client/`: `FrigatebirdClient` interface and Playwright implementation
+- `src/browser/`: auth store, session lifecycle, scrape primitives
+- `src/lib/`: identifiers, option parsing, invocation normalization, config, output
+
+## Skills Files
+
+Frigatebird now includes skill-oriented project files (same ecosystem style used by `x-list-manager`):
+
+- `SKILL.md`: AI-agent usage contract for this CLI
+- `SPEC.md`: technical architecture and command behavior
+- `TASKS.md`: parity/release checklist
+
+## Release Readiness
+
+- `CHANGELOG.md` tracks release notes.
+- `RELEASE.md` contains the release checklist and publish flow.
+- GitHub workflows enforce CI + publish gates:
+  - `.github/workflows/ci.yml`
+  - `.github/workflows/release.yml`
+  - npm publish is triggered by GitHub Release `published` events using npm trusted publishing (OIDC, no npm token secret).
+- `npm run release:check` runs lint + build + full tests + coverage.
+- `npm run smoke:pack-install` validates clean install + binary entrypoint from a packed tarball.
+
+## Test
+
+```bash
+npm run test:run
+npm run test:coverage
+npm run test:e2e
+```
+
+`test:run` and `test:coverage` run unit/integration suites only.
+`test:e2e` runs end-to-end read-only tests against empty-account fixtures.
+
+## Notes
+
+- Frigatebird automates X web UI and depends on selectors that may change.
+- Some deep `bird` GraphQL-only semantics are represented as compatibility flags in Playwright mode.

package/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: frigatebird
+description: Use Frigatebird to interact with X from the CLI with bird-compatible commands plus x-list-manager list automation. Use when users ask to read timelines/tweets, manage follows/lists, or automate list membership without X API keys.
+argument-hint: 'whoami, read https://x.com/user/status/123, search "from:openai", add "AI News" @openai @anthropicai'
+---
+
+# Frigatebird Skill
+
+Frigatebird is a Playwright-first CLI that preserves `bird` command ergonomics and includes `x-list-manager` list operations.
+
+## Use This Skill When
+
+- The user asks for `bird`-style CLI interactions on X.
+- The user wants list automation (`add`, `remove`, `batch`, `refresh`).
+- The user wants browser-cookie-based operation without API keys.
+
+## Core Workflow
+
+1. Verify auth/session health:
+   - `npx tsx src/cli.ts check`
+   - `npx tsx src/cli.ts whoami`
+2. For read-only tasks, prefer JSON output:
+   - `npx tsx src/cli.ts read <tweet-id-or-url> --json`
+   - `npx tsx src/cli.ts search "<query>" --json`
+3. For list-management tasks:
+   - `npx tsx src/cli.ts add "<List Name>" @handle1 @handle2`
+   - `npx tsx src/cli.ts remove @handle "<List Name>"`
+   - `npx tsx src/cli.ts batch accounts.json`
+4. Use pagination controls for large reads:
+   - `--all`, `--max-pages`, `--cursor`, `-n`
+
+## Command Groups
+
+- Posting/mutations: `tweet`, `post`, `reply`, `like`, `retweet`, `follow`, `unfollow`, `unbookmark`
+- Read/timelines: `read`, `replies`, `thread`, `search`, `mentions`, `user-tweets`, `home`, `bookmarks`, `likes`, `list-timeline`, `news`, `about`
+- Identity/health: `check`, `whoami`, `query-ids`, `help`
+- List automation: `refresh`, `add`, `remove`, `batch`, `lists`, `list`
+
+## Options That Matter Most
+
+- Auth/cookies: `--auth-token`, `--ct0`, `--cookie-source`, `--chrome-profile`, `--firefox-profile`
+- Determinism/testing: `--base-url`, `--plain`, `--no-color`
+- Pagination: `-n`, `--all`, `--max-pages`, `--cursor`, `--delay`
+- Output: `--json`, `--json-full`
+- Media posting: `--media`, `--alt`
+
+## Caveats
+
+- This tool depends on X web UI selectors; selector drift can break flows.
+- `query-ids` is retained for command compatibility and does not drive Playwright execution.
+- Some GraphQL-specific behavior from original `bird` is represented as compatibility flags in Playwright mode.

package/SPEC.md

@@ -0,0 +1,59 @@
+# Frigatebird Technical Specification
+
+## Overview
+
+Frigatebird is a TypeScript CLI for interacting with X via browser automation. It targets command-level parity with `bird` and includes list-management capabilities from `x-list-manager`.
+
+## Product Intent
+
+- Preserve the user-facing `bird` command model after `bird` deprecation.
+- Replace unstable/private GraphQL dependency with Playwright-driven web interactions.
+- Consolidate read, mutation, and list-management operations into one CLI.
+
+## Architecture
+
+### 1. CLI Assembly (`src/cli/`, `src/cli.ts`)
+- Declares the command surface with Commander.
+- Normalizes shorthand invocation (`<tweet-id-or-url>` -> `read`).
+- Resolves option precedence: CLI > env > project config > global config.
+
+### 2. Command Handlers (`src/commands/handlers.ts`)
+- Maps CLI actions to client operations.
+- Applies option parsing per command category.
+- Normalizes JSON/plain output behavior.
+
+### 3. Client Layer (`src/client/`)
+- `FrigatebirdClient` interface defines all command capabilities.
+- `PlaywrightXClient` implements behavior through X web navigation and DOM scraping.
+
+### 4. Browser Layer (`src/browser/`)
+- Session lifecycle and login checks.
+- Cookie loading and auth store management.
+- Scraping collectors for tweets, users, lists, and news.
+
+### 5. Shared Library (`src/lib/`)
+- Identifier parsing (`tweet`, `list`, `profile` references).
+- Option parsing and normalization.
+- Output formatting and rendering.
+- Config/env loading and merge precedence.
+
+## Compatibility Model
+
+### bird parity
+- Frigatebird implements the `bird` CLI command/flag interface to maximize drop-in usability.
+- GraphQL-only internals are represented as compatibility behavior where needed.
+
+### x-list-manager parity
+- Frigatebird embeds list automation commands (`add`, `remove`, `batch`, `refresh`) with equivalent UX expectations.
+
+## Testing Strategy
+
+- Unit tests cover parsing, invocation, handler orchestration, and client helper behavior.
+- End-to-end tests run real browser flows against fixture pages for read-only scenarios and empty accounts.
+- Release gate requires lint + build + full test + coverage.
+
+## Operational Constraints
+
+- X DOM/selectors can change without notice.
+- Auth depends on valid browser session cookies or explicit token input.
+- Read-only fixture e2e validates resilient behavior under low/no timeline data.

package/TASKS.md

@@ -0,0 +1,29 @@
+# Frigatebird Parity and Release Tasks
+
+## Parity
+- [x] Match `bird` command surface from a CLI interface standpoint.
+- [x] Keep shorthand tweet read invocation compatibility.
+- [x] Implement pagination and JSON flags across read commands.
+- [x] Support bird-style config/env precedence and key mappings.
+- [x] Keep compatibility behavior for `query-ids` and bookmark expansion flags.
+
+## x-list-manager Integration
+- [x] Include `refresh`, `add`, `remove`, and `batch` commands.
+- [x] Preserve headless/headed toggle behavior with `--no-headless`.
+- [x] Keep result reporting compatible for automation use.
+
+## Architecture
+- [x] Split monolithic implementation into modular layers (`cli`, `commands`, `client`, `browser`, `lib`).
+- [x] Define typed client interface for clear command contracts.
+- [x] Centralize option parsing and output formatting.
+
+## Testing
+- [x] Add/expand unit tests for CLI entry, invocation normalization, options, handlers, and client helpers.
+- [x] Add read-only end-to-end coverage for empty-account conditions.
+- [x] Ensure lint/build/test/coverage all pass before release.
+
+## Release Preparation
+- [x] Add `CHANGELOG.md`.
+- [x] Add `RELEASE.md` release checklist and publish flow.
+- [x] Add `SKILL.md` + `SPEC.md` + `TASKS.md` for agent-oriented usage.
+- [ ] Add mutation-focused e2e coverage against disposable test accounts (post-release hardening).

package/dist/browser/auth-store.js

@@ -0,0 +1,145 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getCookies } from "@steipete/sweet-cookie";
+function normalizeDomain(domain) {
+    if (!domain)
+        return ".x.com";
+    return domain.startsWith(".") ? domain : `.${domain}`;
+}
+function toPlaywrightCookie(cookie) {
+    return {
+        name: cookie.name,
+        value: cookie.value,
+        domain: normalizeDomain(cookie.domain),
+        path: cookie.path ?? "/",
+        expires: cookie.expires ?? -1,
+        httpOnly: cookie.httpOnly ?? false,
+        secure: cookie.secure ?? true,
+        sameSite: cookie.sameSite ?? "Lax",
+    };
+}
+function mapSource(value) {
+    return value;
+}
+export class AuthStore {
+    authFile;
+    constructor(authFile = path.join(process.cwd(), "auth.json")) {
+        this.authFile = authFile;
+    }
+    loadFromDisk() {
+        if (!fs.existsSync(this.authFile))
+            return null;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.authFile, "utf8"));
+            if (!Array.isArray(parsed.cookies) || parsed.cookies.length === 0)
+                return null;
+            return {
+                cookies: parsed.cookies,
+                source: parsed.source ?? "auth.json",
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    save(cookies, source) {
+        const payload = {
+            cookies,
+            source,
+            createdAt: new Date().toISOString(),
+        };
+        fs.writeFileSync(this.authFile, JSON.stringify(payload, null, 2));
+    }
+    clear() {
+        if (fs.existsSync(this.authFile)) {
+            fs.unlinkSync(this.authFile);
+        }
+    }
+    async extractFromBrowser(options) {
+        const browsers = options.cookieSource.map(mapSource);
+        const extraction = await getCookies({
+            url: "https://x.com",
+            browsers,
+            chromeProfile: options.chromeProfileDir ?? options.chromeProfile,
+            firefoxProfile: options.firefoxProfile,
+            timeoutMs: options.cookieTimeout,
+        }).catch(() => null);
+        if (!extraction || extraction.cookies.length === 0) {
+            return null;
+        }
+        const authToken = extraction.cookies.find((cookie) => cookie.name === "auth_token");
+        const ct0 = extraction.cookies.find((cookie) => cookie.name === "ct0");
+        if (!authToken || !ct0) {
+            return null;
+        }
+        const playwrightCookies = [
+            toPlaywrightCookie({
+                name: "auth_token",
+                value: authToken.value,
+                domain: authToken.domain,
+                path: authToken.path,
+                expires: authToken.expires,
+                httpOnly: true,
+                secure: authToken.secure,
+                sameSite: authToken.sameSite,
+            }),
+            toPlaywrightCookie({
+                name: "ct0",
+                value: ct0.value,
+                domain: ct0.domain,
+                path: ct0.path,
+                expires: ct0.expires,
+                httpOnly: ct0.httpOnly,
+                secure: ct0.secure,
+                sameSite: ct0.sameSite,
+            }),
+        ];
+        return {
+            cookies: playwrightCookies,
+            source: `browser:${options.cookieSource.join(",")}`,
+        };
+    }
+    fromManualTokens(options) {
+        if (!options.authToken || !options.ct0)
+            return null;
+        return {
+            source: "manual-flags",
+            cookies: [
+                toPlaywrightCookie({
+                    name: "auth_token",
+                    value: options.authToken,
+                    domain: ".x.com",
+                    path: "/",
+                    httpOnly: true,
+                    secure: true,
+                    sameSite: "Lax",
+                }),
+                toPlaywrightCookie({
+                    name: "ct0",
+                    value: options.ct0,
+                    domain: ".x.com",
+                    path: "/",
+                    httpOnly: false,
+                    secure: true,
+                    sameSite: "Lax",
+                }),
+            ],
+        };
+    }
+    async resolve(options, forceRefresh = false) {
+        const manual = this.fromManualTokens(options);
+        if (manual)
+            return manual;
+        if (!forceRefresh) {
+            const saved = this.loadFromDisk();
+            if (saved)
+                return saved;
+        }
+        const extracted = await this.extractFromBrowser(options);
+        if (extracted) {
+            this.save(extracted.cookies, extracted.source);
+            return extracted;
+        }
+        return null;
+    }
+}