pubkit 0.2.0__tar.gz → 0.3.0__tar.gz

{pubkit-0.2.0 → pubkit-0.3.0}/CHANGELOG.md

@@ -4,6 +4,47 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning is [semantic](https://semver.org/); adapters may change behaviour on
 a minor bump when a platform changes underneath them.
 
+## [0.3.0] — 2026-09-11
+
+Sign-in is the one step a human performs and a machine has to judge, and every
+way it fails is silent. This release makes each of them say something.
+
+### Added
+
+- **`login_preflight()`** — playwright, browser, host reachability, a writable
+  session store and any existing session are checked before a window opens.
+  A login that cannot work no longer costs five minutes to find out.
+- **Live observation during sign-in** — console errors, failed requests and
+  challenge-host scripts are recorded while the human works, and submissions to
+  the platform are counted. A button that never fires is now distinguishable
+  from a bot check that never completes; previously both were silence.
+- **Post-flight proof** — the saved state is checked for cookies on the
+  platform's own domain and for the cookie names that authorise writing, its
+  expiry is reported, and a signed-in page is fetched and checked. **A session
+  is written only after it has been shown to work.**
+- **`pubkit auth login <platform> --attach`** — watch a Chrome you started
+  yourself (`--remote-debugging-port=9222`) instead of launching one, for
+  platforms that will not complete a sign-in in a fresh profile.
+- **`pubkit auth login --minutes`** to set the wait.
+- **`core/login.py`** — one `LoginFlow` per platform declaring success markers,
+  required cookies, cookie domain, probe URL and signed-in markers. A new
+  platform inherits the whole validation suite rather than new special cases.
+- **`tests/fixtures/login_server.py`** — a sign-in page that fails the six ways
+  real ones do: dead button, blocked challenge, partial cookies, short-lived
+  session, ghost session, and the happy path. 26 tests cover the matrix; the
+  unit half needs no browser at all.
+- **Class E in `docs/FAILURE-MODES.md`** — six new entries.
+
+### Changed
+
+- A launched login window now uses a **persistent pubkit profile** and real
+  Google Chrome where it is installed, falling back to bundled Chromium.
+  pubkit does not try to disguise an automated browser; where a platform
+  declines one, `--attach` uses the browser you actually sign in with.
+- `pubkit auth verify` runs the identical post-flight checks as `login`, so a
+  session cannot pass one and fail the other, and prints each finding.
+- `BROWSER_PLATFORMS` derives from the login flow table — one source of truth.
+
 ## [0.2.0] — 2026-09-11
 
 The release that makes `pubkit publish --to medium --confirm` actually work

{pubkit-0.2.0 → pubkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pubkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Publish one source to many platforms, safely. Medium, Substack, X, Dev.to, Hashnode.
 Project-URL: Homepage, https://github.com/arunsingh/pubkit
 Project-URL: Issues, https://github.com/arunsingh/pubkit/issues
@@ -146,8 +146,41 @@ pubkit auth login medium
 ```
 
 A real browser window opens at Medium's login page. You sign in — password
-manager, MFA, device confirmation, whatever it asks for. pubkit watches for the
-post-login URL, saves the session encrypted, and closes the window.
+manager, MFA, device confirmation, whatever it asks for.
+
+Before that window opens, pubkit checks the things that would otherwise cost you
+five silent minutes: playwright, a browser, whether the login host is even
+reachable from here, whether the session store is writable, and whether you
+already have a working session. After you sign in, it checks the cookies are for
+the platform's own domain, that the ones which authorise writing are present,
+how long they last — and then fetches a page only a signed-in user can see.
+**The session is saved only once it has been proven to work.** A saved session
+that does not work is worse than none, because the failure moves into the middle
+of a publish.
+
+If the sign-in button does nothing at all — no error, no request, the single
+most confusing failure there is — pubkit says so, and says which of the two
+causes it was:
+
+```
+  ✗ timeout: no sign-in seen in 5 minutes
+  ! last URL: https://medium.com/m/signin
+  ✗ form submission: the page never sent a sign-in request
+      the button was not wired up, or a script it waits on never finished —
+      try: pubkit auth login medium --attach
+```
+
+`--attach` watches a Chrome you started yourself rather than launching one:
+
+```bash
+open -a "Google Chrome" --args --remote-debugging-port=9222
+pubkit auth login medium --attach
+```
+
+pubkit drives nothing about that sign-in; it watches a tab you are already in.
+It does not try to look like something it is not, and it does not attempt to
+defeat a bot check — where a platform declines an automated browser, `--attach`
+gets out of the way instead.
 
 From then on, unattended:
 
@@ -313,12 +346,16 @@ validate >> PubkitPublishOperator.expand_fanout(
 
 ## Status
 
-v0.1. The core, the checks, the planner and the state machine are tested (32
-tests) and exercised end-to-end against a real published series in
-`examples/inside-ai-infra/`. The browser adapters encode techniques verified by
-hand against live editors; selectors are the part most likely to need a patch
-when a platform ships a redesign, which is exactly why they are isolated in one
-dataclass per adapter.
+v0.3. The core, the checks, the planner, the state machine, the browser pool,
+the table renderer and the sign-in validator are covered by 68 tests, and the
+whole pipeline is exercised end-to-end against a real published series in
+`examples/inside-ai-infra/`. Two hostile fixtures carry most of the weight: an
+editor that strips images, splits content roots and lands figures above the
+caret, and a sign-in page that fails the six ways real ones do.
+
+Selectors remain the part most likely to need a patch when a platform ships a
+redesign, which is exactly why they are isolated in one dataclass per adapter —
+and login flows in one `LoginFlow` per platform.
 
 ## Docs
 

{pubkit-0.2.0 → pubkit-0.3.0}/README.md

@@ -96,8 +96,41 @@ pubkit auth login medium
 ```
 
 A real browser window opens at Medium's login page. You sign in — password
-manager, MFA, device confirmation, whatever it asks for. pubkit watches for the
-post-login URL, saves the session encrypted, and closes the window.
+manager, MFA, device confirmation, whatever it asks for.
+
+Before that window opens, pubkit checks the things that would otherwise cost you
+five silent minutes: playwright, a browser, whether the login host is even
+reachable from here, whether the session store is writable, and whether you
+already have a working session. After you sign in, it checks the cookies are for
+the platform's own domain, that the ones which authorise writing are present,
+how long they last — and then fetches a page only a signed-in user can see.
+**The session is saved only once it has been proven to work.** A saved session
+that does not work is worse than none, because the failure moves into the middle
+of a publish.
+
+If the sign-in button does nothing at all — no error, no request, the single
+most confusing failure there is — pubkit says so, and says which of the two
+causes it was:
+
+```
+  ✗ timeout: no sign-in seen in 5 minutes
+  ! last URL: https://medium.com/m/signin
+  ✗ form submission: the page never sent a sign-in request
+      the button was not wired up, or a script it waits on never finished —
+      try: pubkit auth login medium --attach
+```
+
+`--attach` watches a Chrome you started yourself rather than launching one:
+
+```bash
+open -a "Google Chrome" --args --remote-debugging-port=9222
+pubkit auth login medium --attach
+```
+
+pubkit drives nothing about that sign-in; it watches a tab you are already in.
+It does not try to look like something it is not, and it does not attempt to
+defeat a bot check — where a platform declines an automated browser, `--attach`
+gets out of the way instead.
 
 From then on, unattended:
 
@@ -263,12 +296,16 @@ validate >> PubkitPublishOperator.expand_fanout(
 
 ## Status
 
-v0.1. The core, the checks, the planner and the state machine are tested (32
-tests) and exercised end-to-end against a real published series in
-`examples/inside-ai-infra/`. The browser adapters encode techniques verified by
-hand against live editors; selectors are the part most likely to need a patch
-when a platform ships a redesign, which is exactly why they are isolated in one
-dataclass per adapter.
+v0.3. The core, the checks, the planner, the state machine, the browser pool,
+the table renderer and the sign-in validator are covered by 68 tests, and the
+whole pipeline is exercised end-to-end against a real published series in
+`examples/inside-ai-infra/`. Two hostile fixtures carry most of the weight: an
+editor that strips images, splits content roots and lands figures above the
+caret, and a sign-in page that fails the six ways real ones do.
+
+Selectors remain the part most likely to need a patch when a platform ships a
+redesign, which is exactly why they are isolated in one dataclass per adapter —
+and login flows in one `LoginFlow` per platform.
 
 ## Docs
 

{pubkit-0.2.0 → pubkit-0.3.0}/docs/FAILURE-MODES.md

@@ -220,3 +220,72 @@ Publishing one document to five platforms is a fan-out where any leg can fail.
 > **pubkit:** per-platform token-bucket limiter, bounded exponential backoff
 > with jitter, and per-leg result reporting. One platform failing never blocks
 > the others; the run exits non-zero with a machine-readable summary.
+
+---
+
+## Class E — Sign-in
+
+A login is the only step a human performs and a machine has to judge, and every
+failure in it is silent. These six were all observed against live platforms.
+
+### E1. The submit button does nothing at all
+A sign-in page opens, the email is typed, Continue is clicked, and nothing
+happens. No error, no navigation, no network request, nothing in the console.
+It is the hardest login failure to report because from the outside there is
+nothing to report.
+
+> **pubkit:** the page is watched while the human works. Every POST/fetch to
+> the platform is counted, so "you did not finish" and "the button never fired"
+> stop being the same silence. Zero submissions after a timeout is reported as
+> a failure in its own right, with `--attach` as the next step.
+
+### E2. A bot check that never completes
+Identical symptom to E1, opposite cause: the click *is* handled, but the
+handler waits on a challenge script that a freshly launched browser profile
+never gets a token from. Indistinguishable by eye.
+
+> **pubkit:** requests to known challenge hosts (reCAPTCHA, hCaptcha, Arkose,
+> PerimeterX, DataDome, Turnstile) are recorded separately, and a failed one is
+> named in the diagnosis. The remedy is `pubkit auth login <platform> --attach`,
+> which watches a Chrome the user started themselves. pubkit does not attempt
+> to defeat a challenge; it gets out of the way of one.
+
+### E3. Waiting five minutes for something that could never happen
+playwright not installed, no browser downloaded, the login host unreachable
+behind a VPN or proxy, a session directory that is not writable. Each produces
+the same blank window and the same long wait.
+
+> **pubkit:** `login_preflight()` runs first, synchronously and cheaply. A
+> window is never opened when it cannot work, and each failure names its own
+> fix. It also says when a valid session already exists, so the user is not
+> signed out of something that was working.
+
+### E4. The flow stops at the identity provider
+Sign-in goes through Google or a corporate SSO hop, the redirect back never
+completes, and what gets saved is a session for `accounts.google.com` with no
+cookie for the platform at all.
+
+> **pubkit:** the saved state is checked for cookies on the platform's own
+> registrable domain, and for the specific cookie names that authorise writing.
+> Missing ones are named.
+
+### E5. A session that validates and does not work
+Both session cookies present, correct domain, good expiry — and the signed-in
+page still bounces back to sign-in. Cookie inspection cannot detect this; only
+asking the platform can.
+
+> **pubkit:** before anything is written, a page that renders only for a
+> signed-in user is fetched and checked for a signed-in marker. A session is
+> saved only once it has been *proven* to work. A saved session that does not
+> work is worse than none, because it moves the failure into the middle of a
+> publish.
+
+### E6. A session that expires quietly
+A session cookie with no persistent expiry dies with the browser; one with a
+two-day expiry dies mid-week. Either way the failure surfaces days later,
+inside a publish, looking like something else.
+
+> **pubkit:** expiry is reported at login time, and a lifetime under a week is
+> a warning with the number in it. `pubkit auth verify` re-runs the identical
+> checks on demand — same code path, so a session cannot pass one and fail the
+> other.

{pubkit-0.2.0 → pubkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pubkit"
-version = "0.2.0"
+version = "0.3.0"
 description = "Publish one source to many platforms, safely. Medium, Substack, X, Dev.to, Hashnode."
 readme = "README.md"
 requires-python = ">=3.11"

{pubkit-0.2.0 → pubkit-0.3.0}/src/pubkit/__init__.py

@@ -6,7 +6,7 @@ from .core.loader import load_document, load_series  # noqa: F401
 from .core.runner import Pipeline, RunReport  # noqa: F401
 from .registry import build_adapter, list_adapters, register  # noqa: F401
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 __all__ = [
     "Document", "Series", "Asset", "Figure", "Table", "Heading", "Paragraph", "Code",
     "Pipeline", "RunReport", "load_document", "load_series",