birdclaw 0.9.5 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # CHANGELOG
 
+## 0.11.0 - 2026-07-18
+
+### Highlights
+
+- Choose an existing account independently for each live operation without changing the database's persistent account identity.
+- Start a fully local sample archive with `init --demo` for immediate zero-auth exploration.
+
+### Added
+
+- Select existing accounts per live operation with `--account <username>` or `accounts.default`, including sync, profile hydration, DMs, compose, moderation, and scheduled jobs, without changing persistent database identity. (idea from #97 - thanks @ivankuznetsov)
+- Add explicit `init --demo` sample data for zero-auth offline exploration while keeping normal initialization empty.
+
+### Fixed
+
+- Keep `birdclaw db stats` local-only so it does not block on unrelated macOS archive discovery.
+
+### Dependencies and maintenance
+
+- Update `lucide-react` to 1.25.0, `@tanstack/react-start` to 1.168.30, and the pnpm 10 release pin to 10.34.5.
+
+## 0.10.0 - 2026-07-17
+
+### Highlights
+
+- Connect agents to account-scoped cached tweet search and thread research through a disabled-by-default, bearer-authenticated read-only MCP endpoint.
+- Import named public tweets without X credentials through an explicit read-only FxTwitter opt-in, with durable provenance and third-party disclosure guidance.
+- Run Bird-backed live workflows on Windows through trusted Git Bash discovery, portable-install overrides, and preserved subprocess diagnostics.
+- Move to Node 26.5.0, current direct dependencies, and xurl-first live-transport onboarding while retaining existing private Bird compatibility.
+
+### Added
+
+- Add a disabled-by-default, bearer-authenticated read-only MCP endpoint with strict account, storage, virtual-host, origin, path, request-size, concurrency, and result-size isolation; expose only cached tweet search and thread tools, excluding DMs, live X, OpenAI, filesystem access, and writes. (#95)
+- Add explicit public-tweet import through the fixed read-only FxTwitter endpoint, reject redirects and custom origins, persist `fxtwitter` source rows through backup schema v5, and document the requested-ID and network-metadata disclosure. (#103; proposal #99 - thanks @0xdevalias)
+
+### Transport and platform
+
+- Run Bird subprocesses through trusted Git Bash discovery on Windows, preserve slash-prefixed arguments and diagnostics, and support a documented `BIRDCLAW_BASH_COMMAND` override for portable Git installations. (#94 - thanks @kristofer-atlas)
+- Recommend xurl for new live-transport setups, remove deprecated public Bird installation/repository guidance, preserve existing private Bird compatibility, and report unavailable xurl states as local/archive mode. (#100; issue #93 - thanks @TheAngryPit)
+- Move the supported runtime from EOL Node 25.8.1 to Node 26.5.0, adopt TypeScript 7, and refresh all compatible direct runtime and development dependencies. (#102)
+
+### Testing and maintenance
+
+- Stabilize filtered mention rendering coverage by waiting for the refetched card before exercising reply behavior. (#101)
+- Refresh compatible transitive lockfile resolutions after verifying every direct runtime and development dependency is current. (#104)
+
 ## 0.9.5 - 2026-07-06
 
 ### Fixed

package/README.md

@@ -23,6 +23,7 @@ Status: WIP. Real and usable. Not done. Expect schema churn, transport gaps, and
 - archive import for tweets, likes, followers/following, profiles, and full DMs
 - selective archive re-imports for one stale slice without wiping the rest of the local store
 - archive import for bookmark exports when present
+- explicit, disabled-by-default import of named public tweets through the fixed read-only FxTwitter endpoint, with durable source provenance
 - archive import streams bundled media files into the local originals cache and extracts `video_info.variants[]` for video and animated-GIF rows
 - live authored sync through `xurl`, plus likes and bookmarks through `xurl` or `bird`
 - cache-first followers/following sync through `bird` or `xurl`
@@ -76,9 +77,11 @@ Status: WIP. Real and usable. Not done. Expect schema churn, transport gaps, and
 ### Safety
 
 - local-first by default
+- public FxTwitter import never runs automatically and requires a per-invocation flag that discloses the third-party request tradeoff
 - tests disable live writes
 - CI disables live writes
-- app has no auth layer because it is a local-only tool
+- local web access has no default auth layer; the optional MCP endpoint uses a
+  separate bearer token and still requires a loopback origin connection
 
 ### Runtime Architecture
 
@@ -177,11 +180,11 @@ Notes:
 
 ## Requirements
 
-- Node `25.8.1` or Node 26.x
+- Node `26.5.0`
 - `pnpm`
 - macOS recommended for Spotlight archive discovery
-- `xurl` optional for live reads / writes
-- `bird` optional for cookie-backed likes, bookmarks, mentions, DMs, and write fallback
+- `xurl` recommended for live reads / writes
+- an existing private `bird` installation is optional for cookie-backed likes, bookmarks, mentions, DMs, and write fallback
 - OpenAI API key optional for inbox scoring
 
 ## Install
@@ -221,7 +224,9 @@ birdclaw auth status --json
 birdclaw db stats --json
 ```
 
-`auth status` reports Birdclaw's coarse xurl status. Verify xurl with `xurl whoami` and bird with `bird whoami`. For setup and transport selection, see [Sign in](docs/auth.md).
+Want to explore before importing an archive or signing in? `birdclaw init --demo` fills the local database with sample tweets, DMs, profiles, and links. It makes no network requests; run `birdclaw serve` afterward to browse the demo.
+
+`auth status` reports Birdclaw's coarse xurl status. Verify xurl with `xurl whoami`. If you already have a private bird installation, verify it with `bird whoami`. For setup and transport selection, see [Sign in](docs/auth.md).
 
 Find and import an archive:
 
@@ -231,14 +236,16 @@ birdclaw import archive --json
 birdclaw import archive ~/Downloads/twitter-archive-2025.zip --json
 ```
 
-Don't have an archive yet? Request it from <https://x.com/settings/download_your_data>; X emails a download link when it is ready, which may take a few days. A fresh Birdclaw database needs the archive import to establish account identity before live sync. See [Archive Import → Get an archive](docs/archive.md#get-an-archive).
+Don't have an archive yet? Request it from <https://x.com/settings/download_your_data>; X emails a download link when it is ready, which may take a few days. A fresh or demo Birdclaw database needs the archive import to establish real account identity before live sync. See [Archive Import → Get an archive](docs/archive.md#get-an-archive).
 
-Optional profile hydration through xurl can improve bios, follower counts, and avatars, but it performs live X profile reads and can spend API credits on large archives. In Bird-only mode, the command corrects the seeded local account identity from `bird whoami` without bulk-hydrating imported profiles:
+Optional profile hydration through xurl can improve bios, follower counts, and avatars, but it performs live X profile reads and can spend API credits on large archives. With an existing private bird installation, the command can instead correct the seeded local account identity from `bird whoami` without bulk-hydrating imported profiles:
 
 ```bash
-birdclaw import hydrate-profiles --json
+birdclaw import hydrate-profiles --account steipete --json
 ```
 
+Every command that touches live account auth accepts `--account <username>` (stored IDs also work). To reuse one selection without changing the database identity, set `{"accounts":{"default":"steipete"}}` in `~/.birdclaw/config.json`; an explicit flag overrides it for one operation.
+
 `import archive` is idempotent. Re-running parses follower/following edges into the local follow graph, streams bundled media files under `data/tweets_media/`, `data/direct_messages_media/`, and the other archive media folders into `~/.birdclaw/media/originals/archive/<kind>/<id>/`, and pulls `video_info.variants[]` so archive video and animated-GIF rows carry mp4 URLs for the live media fetcher. Already-extracted files are skipped when size matches.
 
 Re-import only one part of a newer archive when you already have live or local data you want to keep:
@@ -276,6 +283,18 @@ private proxy requires `BIRDCLAW_ALLOW_REMOTE_WEB=1`. To require an app-level
 token too, set `BIRDCLAW_WEB_TOKEN` and send it as `x-birdclaw-token` or a
 `birdclaw_token` cookie.
 
+The same process can expose a separate, read-only Streamable HTTP MCP endpoint
+at `/mcp`. It stays disabled until `BIRDCLAW_MCP_TOKEN` and the exact
+`BIRDCLAW_MCP_PUBLIC_URL` are configured. MCP can search cached tweets and read
+cached threads; it cannot access DMs, sync X, call OpenAI, write files, or invoke
+any compose/moderation API. The token must differ from `BIRDCLAW_WEB_TOKEN`.
+MCP reads the default account unless `BIRDCLAW_MCP_ACCOUNT` selects one account
+by id or handle. The origin remains loopback-only; external access requires a
+dedicated HTTPS hostname whose proxy and Cloudflare Access policy admit exactly
+`/mcp` and deny every other path. See the
+[MCP server guide](https://birdclaw.sh/mcp.html) for client and private-proxy
+configuration.
+
 Use the Sync button in Home, Mentions, Likes, Bookmarks, or DMs to run the matching live sync from the web UI and then reload the local view. Manual sync remains the default because live reads can be slow, auth-dependent, or rate-limited. Home and Mentions also offer opt-in per-account auto-sync at 5m, 10m, 15m, 30m, or 1h intervals; the browser pauses hidden-page runs, prevents overlap, and backs off after failures.
 
 `BIRDCLAW_ALLOWED_HOSTS` applies only to the source `pnpm dev` server, not the
@@ -687,7 +706,7 @@ tail -n 1 ~/.birdclaw/audit/bookmarks-sync.jsonl | jq .
 Current preference:
 
 - `xurl` first
-- `bird` fallback for surfaces where cookie-backed reads work better
+- existing private `bird` installations as a compatibility fallback for surfaces where cookie-backed reads work better
 
 Without `xurl` or `bird`, `birdclaw` still works in local/archive mode.