agentic-facebook 0.4.0__tar.gz

agentic_facebook-0.4.0/.claude/harness-spec.md

@@ -0,0 +1,80 @@
+# Harness Spec — agentic-facebook
+
+## Context
+
+Python 3.11+ package (`hatchling`, `uv`/`pipx` install), CLI entry point `agentic-facebook`, tests via `pytest`, lint/format via `ruff`, hooks via `pre-commit`. Published to PyPI as `agentic-facebook` (v0.3.0, 2026-07-20). Single maintainer.
+
+The repo already carries a `CLAUDE.md` of general behavioral guidelines (minimum code, surgical changes, goal-driven execution) that is about *developing* this package. This harness pass adds the first component about *using* the shipped tool.
+
+## Goals
+
+> "`.claude/skills/facebook` — a skill that drives the just-published agentic-facebook v0.3.0 CLI. It must teach Claude to chain the primitives (fetch/feed/comments/post/search/group) for real multi-hop tasks, carry the ban-risk and third-party-PII guidance as why-backed rules, and document the Post/Comment/Entity schemas so outputs are parsed without guessing."
+
+From plan §8 (D7): the skill installs the published package (`uv tool install agentic-facebook`) and shells out to `agentic-facebook`. The division of labor the whole v0.3.0 design rests on: **the CLI does fast structured retrieval, the LLM does the navigation reasoning.** There is deliberately no `crawl` command — chaining is this skill's job.
+
+## Behavior inventory
+
+| id | behavior/knowledge/constraint | layer | component | status |
+|----|-------------------------------|-------|-----------|--------|
+| B1 | Ensure the CLI is installed and the session is live before retrieving | skill | facebook/SKILL.md | generated |
+| B2 | Which primitive to reach for (flags themselves come from `agentic-facebook catalog`) | skill | facebook/SKILL.md | generated |
+| B3 | Chain primitives for multi-hop tasks (the core value) | skill | facebook/SKILL.md | generated |
+| B4 | Results go to a **file**, not stdout — read the file | skill | facebook/SKILL.md | generated |
+| B5 | Exit codes carry meaning; 4 and 7 are not plain failures | skill | facebook/SKILL.md | generated |
+| B6 | Ban-risk discipline (throwaway account, rate floors, no tight loops) | skill | facebook/SKILL.md | generated |
+| B7 | Third-party PII discipline (don't commit, minimize, delete) | skill | facebook/SKILL.md | generated |
+| B8 | Post vs Comment vs Entity, and which fields chain | skill | facebook/SKILL.md | generated |
+| B9 | Recovery when retrieval fails (expiry, checkpoint, doc_id rotation) | skill | facebook/SKILL.md | generated |
+
+## Component specs
+
+### `.claude/skills/facebook/SKILL.md`
+
+- **Directory name `facebook`** — that is the invocable name (`/facebook`), independent of the frontmatter `name`.
+- **Scope: repo-local only** (user decision, 2026-07-20). It therefore triggers only in sessions working inside this repository; copying the directory to `~/.claude/skills/facebook` would make it available everywhere, at the cost of not shipping with a clone.
+- **`description`**: triggers on Facebook data requests phrased by *intent*, not just the keyword — "what has X been posting", "who commented on this", "find people/groups about Y", "check my feed". Names near-misses explicitly: *developing/testing this package itself* is out of scope (ordinary repo work), as is any other social network.
+- **`allowed-tools`**: `Bash(agentic-facebook:*)`, `Read` — every step shells out to `agentic-facebook` and then reads the JSON it wrote; without this the skill stalls on a permission prompt per command.
+- **Auto-triggerable** (no `disable-model-invocation`): retrieval is user-initiated and read-only. It is *not* a deploy-shaped side effect. Ban/PII risk is handled by in-body rules, not by hiding the skill.
+- Body: preflight (install/login/status) → the six primitives as a compact table → chaining recipes → the schema orientation → the two rule sets (ban risk, PII), each stated as principle + why.
+
+### Single file — no `references/`
+
+Failure handling lives in SKILL.md, not a reference file. It was split out initially on an "it worked vs it failed" branch, then merged: that is an *appendix*, not a branch (the model never chooses between the two files, it reads the second in addition), and the highest-stakes instruction in the whole skill — exit 3 means stop, never retry a checkpointed account — had ended up behind a file that only opens after something already went wrong. At ~140 lines merged, the happy-path cost of inlining it is small next to that risk.
+
+## Design rationale
+
+- **One skill, not several.** `fetch`/`feed`/`comments`/`post`/`search`/`group` share one trigger context ("get me something off Facebook") and a single multi-hop task uses several of them *together* — a user thinks of this as one job. Six skills would burn six description slots out of the shared ~1% listing budget to answer the same trigger.
+- **One file, no `references/`.** See the component spec: the failure material is an appendix rather than a branch, and burying the checkpoint stop-rule behind a second file put the most safety-critical line where it loads only after the damage. Splitting the primitives per-command would have been worse still — a chain needs them in the same breath.
+- **Reference data is pointed at, not transcribed** — extended in v0.3.1 from schemas to the whole CLI surface. `agentic-facebook catalog` reports commands, flags, exit codes, output contract, object types and limitations, all derived from the live parser and the `to_dict()`-anchored schema functions. The skill therefore carries **no** command/flag table: a copy would describe whichever version was current when it was written, and a model trusts a copy over its own reading. What stays in the skill is judgment the catalog cannot carry — which primitive to reach for, how to chain, and the ban/PII rules.
+- **No hook, no permissions entry.** Nothing here must be *enforced* — the guardrails that genuinely must not fail (the ≥1.0s active floor, the ≥0.5s scroll floor) are already clamped inside the package and cannot be bypassed from the CLI at all. A hook would be re-implementing, less reliably, a guarantee that already exists in code.
+- **No CLAUDE.md pointer.** The existing CLAUDE.md is about developing this package and is loaded every session; scraping Facebook is not something every session needs. Adding a line would spend the always-on budget on a rarely-relevant pointer.
+
+## Validation
+
+Scenarios for the optional e2e pass:
+1. "What has <profile> been posting lately?" → expects `fetch --limit`, then reads the output file rather than expecting stdout.
+2. "Who commented on <post URL>, and what else do those people post?" → expects `comments` → collect `author_url` → `fetch` per author, with a sane `--limit` rather than an unbounded fan-out.
+3. "Find Facebook groups about <topic>" → expects `search --type groups`, and parses `kind`-bearing Entity objects rather than looking for post fields.
+4. Failure path: a command exits 2 → expects the skill to route to `agentic-facebook login` rather than retrying blindly.
+
+Most recent run: **2026-07-20, 4/4 passed** (~$1.88, ~10 min total), against package v0.3.1 installed from PyPI.
+
+| # | Scenario | Verdict | Evidence |
+|---|---|---|---|
+| V1 | "피드에서 최근 글 5개 요약" | **pass** | `Skill: facebook` → `catalog` → `status` → `feed --limit 5 --output /tmp/...` → `Read` the file (not stdout) → `rm` the file unprompted |
+| V2 | multi-hop: busiest post → its commenters → their timelines | **pass** | `feed --limit 15` → picked max `comment_count` → `comments <url>` → distinct `author_url` → `fetch` ×3; substituted 2 authors whose timelines were empty **and reported having done so** |
+| V3 | "'seoul' 관련 그룹 찾아줘" | **pass** | `search --type groups --limit 25` → took each Entity `id` → `group <id>` ×9 to check liveness; ranked by reaction/comment counts, not post frequency |
+| V4 | near-miss: "이 저장소의 파서 테스트 실행" | **pass** | `skill_invocations: []` — correctly read as ordinary repo work, ran pytest |
+
+Two things the run established beyond the scenarios themselves:
+- The **headless mechanism works**: `claude -p` spawned from Bash is authenticated here, so `run_e2e.py`'s permission approach (`--isolate` + skip-permissions) is confirmed for this project and no longer needs flagging as unverified.
+- The PII rules are followed **without being asked** — every scenario deleted its scraped temp files at the end.
+
+Defects the run surfaced (both fixed): the skill only handled a *missing* install, not an *outdated* one (the machine had 0.2.0, which lacks `catalog` and five primitives); and e2e `transcript.jsonl` files carry scraped PII while the repo's `*.json` ignore rule does not cover `.jsonl`.
+
+## Change history
+
+- 2026-07-20 — **new**. First harness pass on this repo. Recovered a spec from disk (an empty `.claude/skills/facebook/` placeholder existed, no SKILL.md). Generated the `facebook` skill (SKILL.md + references/troubleshooting.md) after the v0.3.0 PyPI release. `validate_harness.py`: 0 errors, 0 warnings. Scope set to repo-local per user. No hooks, permissions, agents, or CLAUDE.md changes — rationale above.
+- 2026-07-20 — **improve**. Rewired the skill onto `agentic-facebook catalog` (added in package v0.3.1): removed the transcribed command/flag table and the duplicated exit-code and limitations tables from SKILL.md and troubleshooting.md, leaving each pointing at the derived source. Removes the package/skill drift risk that a copied table carried, which matters once the skill is used against a PyPI-installed package rather than this checkout.
+- 2026-07-20 — **improve**. Merged `references/troubleshooting.md` into SKILL.md (user call, agreed): the split was an appendix, not a branch, and it had hidden the exit-3 stop-rule behind a conditional load.
+- 2026-07-20 — **validate**. Ran the 4 e2e scenarios: 4/4 pass. Fixed two defects they surfaced (outdated-install handling in the skill; `.jsonl` PII leak in .gitignore). Transcripts deleted after grading.

agentic_facebook-0.4.0/.claude/skills/facebook/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: Facebook retrieval
+description: Read Facebook via the agentic-facebook CLI — a profile's posts, your home feed, a post's comments, search (people/pages/groups/posts), or a group's feed — and chain those results to answer multi-hop questions. Use whenever the user wants something off Facebook, however they phrase it: "what has <person> been posting", "who commented on this", "what is <person>'s circle talking about", "find groups about X", "check my feed", "look up <name> on Facebook". Also use when the user hands over a facebook.com URL and wants its contents. NOT for developing or testing the agentic-facebook package itself (that is ordinary repo work), and not for any other social network.
+allowed-tools: Bash(agentic-facebook:*), Read
+---
+
+# Facebook retrieval
+
+`agentic-facebook` gives you fast, structured retrieval. **You supply the navigation.** The CLI is deliberately a set of single-purpose primitives with no `crawl` command — deciding which handle to follow next is your job, and it is the whole reason this skill exists.
+
+## Step 1 — make sure you're on the current version
+
+Do this before anything else, every task: compare what's installed against what PyPI has.
+
+```bash
+agentic-facebook --version 2>/dev/null
+curl -s --max-time 5 https://pypi.org/pypi/agentic-facebook/json \
+  | python3 -c "import json,sys; print(json.load(sys.stdin)['info']['version'])"
+```
+
+If they differ, upgrade **now, before starting work** — not later, mid-task. Upgrading between steps of a running job can change a flag or an output shape underneath you and turn a clean failure into a baffling one; upgrading before anything is in flight is free.
+
+Don't rely on a command erroring to tell you you're behind. That signal only fires when a release *adds* a command — a release that fixes a bug or changes a default is invisible to it, and "my install still works" is not evidence of being current. `catalog` describing your build correctly says nothing about whether a newer build exists.
+
+Being current matters more here than for most tools: the single most likely way this package breaks is Facebook rotating the query ids it replays, and the fix ships as a release. "Behind on version" and "silently returning nothing" are the same problem often enough that the check pays for itself.
+
+If PyPI is unreachable, **carry on with what's installed** — a version check is a nicety, not a gate, and blocking a task that would have worked is the worse failure.
+
+Two failure shapes also mean install-or-upgrade, if you skipped the check:
+
+- `command not found` → not installed.
+- `invalid choice: '<command>'` → installed but older than this skill expects. Never conclude the feature doesn't exist and work around it.
+
+Install or upgrade from PyPI into its own isolated environment:
+
+```bash
+uv tool install --upgrade agentic-facebook     # or: pipx install --force agentic-facebook
+agentic-facebook setup                                    # one-time: provisions its own browser
+agentic-facebook --version                                # confirm it now matches PyPI
+```
+
+Use `uv tool` or `pipx`, **not** `pip install` into a virtualenv you share with anything else. This package depends on `scrapling[fetchers]`, which pins exact Playwright/patchright versions — dropping it into a shared environment can fail to resolve, or silently break the other Playwright-based tool already living there. If neither `uv` nor `pipx` exists, install one rather than reaching for bare `pip`.
+
+If an upgrade appears to do nothing (still the old version afterward), add `--no-cache`: `uv` caches the package index, so a release published minutes ago can be invisible to a plain `uv tool install --upgrade` while being perfectly present on PyPI.
+
+Note that a repo checkout of this project and the installed CLI are **different things**: running from source (`PYTHONPATH=src python -m agentic_facebook.cli`) can be a completely different version from whatever `agentic-facebook` on PATH resolves to. The version on PATH is the one that counts.
+
+## Step 2 — ask the tool what it can do
+
+```bash
+agentic-facebook catalog          # or: agentic-facebook catalog --json
+```
+
+`agentic-facebook catalog` prints every command with its real flags, the exit-code contract, the output contract, the object types, and the known limitations — **in one call.** Work from what it says.
+
+This file deliberately does **not** restate that list. The catalog is generated from the CLI's own parser, so it is correct for the version actually installed; a table copied into this file would silently describe the wrong version the moment the package updates, and you'd trust the copy over the truth. Anything you need to *call* a command comes from the catalog. What follows is only what the catalog can't carry: how to decide what to call next.
+
+## Step 3 — check the session
+
+Retrieval needs a logged-in Facebook session. Check once at the start of a task, not before every command:
+
+```bash
+agentic-facebook status          # exit 0 = ready; exit 2 = needs login; exit 3 = checkpoint
+```
+
+If exit 2: **`agentic-facebook login` opens a real browser window and needs a human to log in** — it detects completion automatically and times out. You cannot complete it for the user; ask them to, then re-check `status`. The account should be a throwaway, not their main one (see Ban risk).
+
+Any other non-zero exit → see "When something fails" at the end of this file. Read it *before* improvising a retry: for one of these codes, retrying is the wrong move and can get the account banned.
+
+## The one thing that will trip you up
+
+**Every retrieval command writes its results to a JSON *file* and prints only a one-line summary to stderr. Nothing useful goes to stdout.** Run a command and read the file — never expect to parse the command's own output.
+
+```bash
+agentic-facebook feed --limit 10 --output /tmp/feed.json    # stderr: "10 posts, range ... Saved to /tmp/feed.json"
+```
+
+Then `Read /tmp/feed.json`. Always pass `--output` with a path you choose; without it the file lands under the platform data directory with a timestamped name you'd then have to go hunting for.
+
+## What each primitive is *for*
+
+The catalog gives you the flags; this is the judgment about which to reach for. Two questions place any of them, including one added after this was written: **what handle does it take** (a name, a URL, a free-text query, nothing at all) and **how narrow is what it returns**. Prefer the command whose handle you already hold, and among those the narrowest — a targeted surface is fewer requests and less unrelated third-party data than a broad one filtered afterward.
+
+- **`fetch <profile>`** — one person's timeline. The only surface with a real date filter, so any "what did X post in <period>" question starts here.
+- **`feed`** — your own news feed. Use for "what's happening", never for a question about a specific person (their timeline is more complete and filterable).
+- **`post <url>`** / **`comments <url>`** — a specific post you already have a URL for. `post` fills the gap that a feed query cannot return a single permalink.
+- **`search <query>`** — discovery when you have no handle yet. Returns *Entities* (people/pages/groups) or *Posts* depending on `--type`; entities are handles to fetch with, not answers.
+- **`group <group>`** — one group's feed, once search or a link has given you the group.
+
+## Chaining — the actual work
+
+Every `Post` carries `url`, `author_url`, `author_id`; every `Comment` carries `author_url`; every `Entity` carries `id` and `url`. Those are the handles:
+
+- a post's **`url`** → `comments` or `post`
+- any **`author_url`** (post author, or commenter) → `fetch`
+- a group Entity's **`id`** → `group`
+
+**"What is X's circle discussing?"** → `fetch X` → read the file → collect `author_url` of the people X shares from → `fetch` each (with a `--limit`) → summarize across the results.
+
+**"Who engaged with this post, and what are they into?"** → `comments <url> --limit 20` → collect distinct `author_url` → `fetch` each `--limit 5`.
+
+**"Find the active groups about <topic>"** → `search "<topic>" --type groups` → take each Entity's `id` → `group <id> --limit 10` to see whether it is actually alive.
+
+The `--limit` values above are illustrative, not defaults to copy. Size every one from the question being asked: "is this group alive" needs a handful of posts, "what has she been arguing about this month" needs a date window and more. A number carried over from an example is a number nobody chose.
+
+Two rules that keep a chain from turning into a crawl. **Bound the fan-out before you start it** — decide the shape ("the most-engaged commenters"), not "everyone", because each hop is a real request against a real account (see Ban risk). And **report the shape of what you did**: which hops you took, how many you skipped, and why. A chain that silently sampled 5 of 60 commenters and presents itself as "what the commenters think" is a wrong answer wearing a confident summary.
+
+## Reading the output
+
+Three object types. Tell them apart by a field, never by guessing from context:
+
+- **`Post`** — has **`source`** (`timeline` | `newsfeed` | `group` | `search`), telling you which surface it came from; matters once you merge results from several commands into one pile.
+- **`Comment`** — has **`depth`** (`0` = top-level, `≥1` = a reply) and `parent_id`. Its `post_id` matches the parent post's `id`, so comments and posts join on that.
+- **`Entity`** — has **`kind`** (`person` | `page` | `group`). Only `search --type people|pages|groups` returns these. It is a *light* record — name/url/id/verified, no posts — so an Entity is a handle to fetch with, not an answer in itself.
+
+For the full field list run **`agentic-facebook schema`** (or read `object_types` in `agentic-facebook catalog --json`). Prefer that over assuming: both are generated from the code itself, so they cannot drift the way a copy in this file would.
+
+Two fields that mislead if you skim: `captured_at` is when *you* scraped it, never a dedup or sort key — use `id` to dedup and `created_at` to sort. And `created_at` can be `null` when the date could not be located, so filter before comparing dates.
+
+## Ban risk — why this stays slow
+
+The account doing the scraping is at genuine risk of a checkpoint or permanent ban; automating any Meta account violates its Terms of Service. This is why the package clamps a **≥1.0s floor between active requests** and **≥0.5s between scrolls**, in code, un-bypassable — do not try to work around them, and do not fabricate concurrency by launching several `agentic-facebook` processes at once, which defeats the floor just as effectively as disabling it.
+
+What that means for how you work: **a deep chain costs real requests and real risk.** `comments --replies` spends one extra request per commented comment, so a 100-comment post is a burst. Deep pagination (`--max-pages`, default 20) multiplies it. So prefer a `--limit` that answers the question over one that exhausts the source, and when a user asks for something genuinely large, say what it will cost before starting rather than discovering it halfway. If a command returns exit 3 (checkpoint), **stop entirely** — retrying a flagged account is how a temporary block becomes a permanent one.
+
+## Third-party data — why the output is sensitive
+
+Scraped output is other people's personal data: names, profile URLs, full comment text, and signed media URLs. Collecting it can make the *user* a data controller under GDPR/CCPA, with real obligations. `comments` and `search` are the sharp edge here — they collect people who never posted anything to the user and have no relationship with them.
+
+So: **write output to a temp path, not into the repo**, and never `git add` it (the repo gitignores `*.json`/`*.ndjson` precisely because of this — don't defeat it with `--output` into a tracked path). Retrieve the narrowest thing that answers the question rather than everything available. When the task is done, say that the files can be deleted, and delete them if you created them for an intermediate step. Quote individuals' text only when the user's question actually needs the quote — a summary usually does the job with less exposure.
+
+`--raw` embeds the unparsed node and is redacted by default; `--no-redact` disables even that. Neither belongs in normal use — they are debugging aids for working on the scraper itself.
+
+## When something fails
+
+`agentic-facebook catalog` prints what each exit code *means*. Below is what to *do* — and the theme is that **most failures here are informative, not transient. Retrying the same command is almost never the fix.**
+
+**Exit 3 — checkpoint. Stop immediately.** Meta has flagged the account with a security challenge, and retrying is *actively harmful*: hammering a checkpointed account is how a temporary block becomes a permanent ban. Abandon the task, tell the user their account needs clearing by hand in a real browser, and run no further `agentic-facebook` commands this session. If checkpoints recur across sessions, that's a signal about volume — the fix is smaller `--limit`s and fewer hops, not a fresh login.
+
+**Exit 2 — session expired.** Routine; sessions die. `agentic-facebook login` opens a real browser and needs a human — you cannot complete it. Ask the user, then re-check `status`. Note `status` inspects the response body, not just the URL, because Facebook serves its login form in place at `facebook.com` with HTTP 200 and no redirect: a dead session looks perfectly healthy from outside. If `status` says expired while a browser looks logged in, trust `status`.
+
+**Exit 4 — zero results is ambiguous.** Either genuinely nothing there (empty timeline, no hits, no comments) or parser drift / `doc_id` rotation. Distinguish with one command: run something you *know* returns data (`agentic-facebook feed --limit 3`). If that also returns 0, it isn't your target — see rotation below. If the feed works, the emptiness is real; report it.
+
+**Exit 7 — `--since` unconfirmed.** You have *some* posts but can't claim they're all of them in that range. Never present it as complete: either say the range is partial, or re-run with `--mode active` (if it had fallen back) or a larger `--max-scrolls`.
+
+**`doc_id` rotation — the one real fragility.** Active mode replays Facebook query ids that rotate when Facebook ships a client build. `fetch` survives it (falls back to the browser automatically — you'll see `active mode failed ...; falling back to browser`, and it'll be much slower). `feed`, `comments`, `post`, `search`, `group` do **not**: they're active-only and simply fail. The signature is several active-only commands failing at once while `fetch --mode passive` still works. That's a package-level fix, not something to work around — tell the user and check for a newer release (`agentic-facebook catalog` reports the installed version).
+
+**Not bugs, though they look like it:** a hop that fell back to passive is missing the profile's newest post (structural — re-run that hop with `--mode active`); `post`/`comments` on a **reel URL** fails with `could not find a story id` and needs a regular permalink; a comment's `reply_count` can exceed what `--replies` returned, because the count includes deeper nesting and only depth-1 is fetched.

agentic_facebook-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-test:
+    # macOS is the first-class, tested target (v1); the ubuntu leg exists
+    # because the fixture/parse/CLI layer is browser-agnostic, and running it
+    # on Linux too is a cheap way to make that cross-platform claim real
+    # (plan §14). Neither leg installs an actual browser binary.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install pinned dev dependencies
+        run: python -m pip install -r requirements-dev.lock
+
+      - name: Install package (dependencies already pinned above)
+        run: python -m pip install -e . --no-deps
+
+      - name: Ruff lint
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+      - name: Fixture PII/secret scan
+        run: python scripts/check_fixtures_pii.py
+
+      - name: Run tests
+        run: pytest
+
+  build-and-smoke:
+    # A wheel-install smoke test, WITH scrapling (a real dependency) but
+    # WITHOUT a browser binary — that's a separate, explicit `agentic-facebook setup`
+    # step this job never runs. This catches a wrong entry-point path, a
+    # missing runtime dep, or an import that only fails once scrapling is
+    # actually present (plan §13) — none of which the fixture tests touch.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: python -m pip install build
+
+      - name: Build wheel
+        run: python -m build --wheel
+
+      - name: Install built wheel into a clean venv
+        # POSIX venv layout (bin/, not Scripts\) and the bash default shell
+        # both assume macos-latest/ubuntu-latest only — adding windows-latest
+        # to the matrix above would need this step rewritten, not just the
+        # matrix line (Windows unsupported in v1; see README/pyproject).
+        run: |
+          python -m venv smoke-venv
+          smoke-venv/bin/pip install dist/*.whl
+
+      - name: Smoke test the entry point
+        run: |
+          smoke-venv/bin/agentic-facebook --version
+          smoke-venv/bin/agentic-facebook --help
+          smoke-venv/bin/agentic-facebook schema

agentic_facebook-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+# Fires when a GitHub Release is published (Releases page -> "Draft a new
+# release" -> pick/create tag vX.Y.Z -> Publish release) — NOT on a bare
+# `git push --tags`, which creates the tag but no visible Release entry.
+# github.ref_name still resolves to the release's tag name under this event.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches pyproject.toml version
+        run: python3 scripts/check_tag_version.py "${{ github.ref_name }}"
+
+      - name: Install build tool
+        run: python -m pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      # Required to mint the OIDC token for PyPI Trusted Publishing — there is
+      # no stored API token anywhere in this repo (plan §15).
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      # Pinned to the commit for release v1.14.0 — a floating tag on an
+      # action that runs with publish credentials is a hijack vector
+      # (plan §15). Bump deliberately, not automatically.
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

agentic_facebook-0.4.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Dev environment
+.venv/
+.ruff_cache/
+.pytest_cache/
+
+# Raw captures and runtime outputs are a PII trap — ignore by an unambiguous,
+# distinct name/location so a safe fixture and an unsafe raw capture can never
+# collide under one glob (see plan §4).
+scratch/
+*.raw.ndjson
+profiles/
+*.json
+*.ndjson
+
+# Un-ignore the committed, synthetic-by-construction fixtures — enumerated
+# explicitly, NOT a wildcard. A wildcard un-ignore (`!tests/fixtures/*.ndjson`)
+# would re-include ANY new .ndjson dropped into this directory, not just
+# these known-synthetic ones — defeating the whole point of the blanket
+# ignore above. Adding a new fixture means adding its name here too.
+!tests/fixtures/basic_status_post.ndjson
+!tests/fixtures/comment_preview_and_universal_marker.ndjson
+!tests/fixtures/media_and_links.ndjson
+!tests/fixtures/pinned_decoy_and_missing_date.ndjson
+!tests/fixtures/shared_post.ndjson
+!tests/fixtures/split_defer_merge.ndjson
+!tests/fixtures/truncated_post.ndjson
+
+# E2E harness runs capture full session transcripts, which contain whatever the
+# run scraped — real names, comment text, profile URLs. `.jsonl` is NOT covered
+# by the *.json rule above, so it needs its own entry (learned the hard way).
+.claude/.e2e-runs/
+*.jsonl
+
+# Scratch space for vendored reference material and sibling working copies —
+# 355MB / 3400+ files at the time of writing. Never part of this package.
+.tmp/
+
+.DS_Store

agentic_facebook-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: fixture-pii-scan
+        name: scan committed fixtures for PII/secrets
+        entry: python3 scripts/check_fixtures_pii.py
+        language: system
+        files: ^tests/fixtures/.*\.ndjson$
+        pass_filenames: false

agentic_facebook-0.4.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] — Renamed to Agentic Facebook
+
+Renamed from the old identity (formerly PyPI `scraper-for-facebook`, import
+`scraper_for_facebook`, CLI `scrape-fb`, repo `Scraper-for-Facebook`) to
+**Agentic Facebook**. Behaviour is unchanged. Breaking: the import path, CLI
+command, PyPI package name, and base exception class (`ScraperForFacebookError`
+→ `AgenticFacebookError`) all changed. Install `agentic-facebook`; the old
+package is a tombstone pointing here.
+
+## [0.3.2] - 2026-07-21
+
+### Fixed
+- **`FacebookScraper(profile=...)` used the wrong account's cached credentials.** Active mode keys its token cache by profile *name* while the browser session is keyed by *directory*; the Python facade forwarded only the directory, so a non-default profile drove one account's browser while reading — and overwriting — the token cache belonging to `default`. With a populated cache that meant retrieving as the wrong account, and either way it corrupted the other profile's cached cookies. Silent rather than a crash. Affects the Python API only with a non-default `profile`; the CLI was never affected. Introduced in 0.3.0.
+
+### Changed
+- The PyPI summary and keywords now match the README and the repository description, instead of still describing the v0.2.0 browser-only scraper. Package metadata is frozen per release, so this could only be corrected by publishing.
+
+### Documentation
+- The whole documentation set rewritten for v0.3.x: twelve `docs/wiki/` pages (adding Architecture and Chaining-Recipes), a rewritten README, and CONTRIBUTING / SECURITY / CODE_OF_CONDUCT at the repository root. Pages now defer to `agentic-facebook catalog` and `agentic-facebook schema` for anything the CLI can describe about itself.
+
+
+## [0.3.1] - 2026-07-20
+
+### Added
+- **`agentic-facebook catalog [--json]`** — the CLI describing itself: every command and flag, the exit-code contract, the output contract, the object types, and the known limitations, in one call. It is **derived, not authored**: commands and flags are introspected from the live `argparse` parser, object types come from the same `to_dict()`-anchored functions `schema` uses, and exit codes come from a single table. Anything that needs to explain this tool (docs, an agent, a `.claude` skill) can now read it instead of transcribing it and drifting.
+- `tests/test_catalog.py` enforces that derivation: adding a command or flag without it appearing in the catalog fails the suite, as does a subcommand with no handler.
+
+### Changed
+- Exit codes moved from scattered integer literals in `cli.py` into `exits.py`, which is now the single source for both the CLI's behavior and its description. No exit code changed value.
+
+
+## [0.3.0] - 2026-07-20
+
+Adds an **active transport** — reading Facebook's GraphQL API over plain HTTP,
+with the browser needed only to log in — and turns the single-purpose scraper
+into a set of composable primitives. Additive: `fetch`'s existing flags and
+output schema are unchanged apart from one new field.
+
+### Added
+- **Active mode.** `fetch` now reads `/api/graphql/` over HTTP by default, paginating by cursor with no browser in the hot path, and falls back to the browser transport automatically when it fails (`--mode auto|active|passive`). Both transports share one parser, so their output is identical.
+- **New commands**, each emitting the same output contract as `fetch`:
+  - `feed` — your home news feed.
+  - `comments <post_url>` — a post's comments, `--sort top|recent`, `--replies` for depth ≥ 1.
+  - `post <post_url>` — a single post by permalink (which a feed query cannot return).
+  - `search <query>` — `--type top|posts|people|pages|groups`.
+  - `group <group_url_or_id>` — one group's feed.
+- **`Comment` and `Entity` schemas**, both covered by `agentic-facebook schema` / `schema --json`.
+- `Post.source` (`timeline` | `newsfeed` | `group` | `search`) so chained output stays self-describing.
+- `agentic-facebook login --from-chrome` (opt-in): import an existing session from local Chrome by decrypting its cookie DB. Needs the `chrome` extra: `pip install 'agentic-facebook[chrome]'`. See DISCLAIMER §6 — this is literal cookie extraction and usually imports your main account.
+- A **non-bypassable active-request floor** (`--request-interval`, MIN clamped to ≥ 1.0s, jittered), the active-mode counterpart to the scroll-pause floor. Applies to every active request, including id-resolution GETs.
+- `--max-pages` (default 20) bounds active pagination depth.
+- Opt-in live tests under `tests/live/` (`SFB_LIVE_TESTS=1`), including an active-vs-passive parity test.
+
+### Fixed
+- **`status` reported a dead session as `logged_in`.** `detect_wall()` only inspected the URL, but Facebook serves its login form in place at `https://www.facebook.com/` with HTTP 200 and no redirect. It now also inspects the response body, and treats a missing `DTSGInitialData` token as logged out.
+- **`login` could not be driven non-interactively.** It blocked on `input()`, which hung forever under a non-TTY driver while holding the Chromium profile lock, blocking every later browser launch. It now polls the browser's own state and honors `--timeout-seconds`.
+
+### Changed
+- `--since`/`--until` are now a **precise server-side filter** in active mode (verified: they change which posts the server returns, not just which are kept). They remain best-effort in passive mode, still reported via exit code 7.
+- Token refresh prefers a cheap HTTP re-read over relaunching the browser.
+- README/DISCLAIMER repositioned: active mode uses *your own session's* tokens the way your browser does — still no credential injection and no foreign-token replay — and the DISCLAIMER now covers the much larger third-party PII surface that `comments`/`feed`/`search` collect.
+
+### Known limitations
+- `feed`/`comments`/`post`/`search`/`group` are active-only: they have no passive equivalent to fall back to if a `doc_id` rotates.
+- Passive mode cannot see a profile's newest post (the first timeline batch is server-rendered, never fetched as a GraphQL XHR). Active mode can.
+- `post`/`comments` do not support reel URLs (a reel page embeds no story id).
+- `--replies` fetches depth-1 replies only.
+
+## [0.2.0] - 2026-07-07
+
+### Added
+- `agentic-facebook schema`: prints the `fetch` output object schema (field name, JSON type, one-line meaning), offline and always exit 0; `--json` emits JSON Schema (draft 2020-12). Anchored on `Post.to_dict()`'s actual output keys, not the dataclass fields, so it can't mis-document `raw` as always-present.
+- Every `fetch`/`login`/`status`/`doctor` flag now has a `--help` string with its human-readable default, so `--help` is authoritative standalone without reading source.
+
+### Changed
+- No behavior change to `login`/`status`/`setup`/`doctor`/`fetch` themselves — additive only.
+
+## [0.1.0] - 2026-07-05
+
+### Added
+- Initial release: `agentic-facebook login` / `status` / `setup` / `doctor` / `fetch`.
+- Logged-in Facebook timeline scraping via GraphQL XHR observation (no token replay).
+- `--limit`, `--since`/`--until` retrieval with stop-reason reporting.
+- JSON and NDJSON output formats.
+- Python API: `FacebookScraper`, `Post`, `Media`, `LinkAttachment`.
+
+[Unreleased]: https://github.com/tjdwls101010/Agentic-Facebook/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/tjdwls101010/Agentic-Facebook/releases/tag/v0.2.0
+[0.1.0]: https://github.com/tjdwls101010/Agentic-Facebook/releases/tag/v0.1.0

agentic_facebook-0.4.0/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.