pubkit 0.1.1__tar.gz → 0.3.0__tar.gz

pubkit-0.3.0/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+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
+unattended. 0.1.x could plan a Medium publish; it could not perform one.
+
+### Added
+
+- **Browser lifecycle** (`browserctl.BrowserPool`, `attached()`). This was the
+  missing seam: the runner called `adapter.authenticate()` on a `MediumAdapter`
+  whose `_page` was still `None`. Now one browser serves the whole run, one
+  context per platform so a Medium session is never presented to Substack, and
+  sessions are refreshed on the way out because cookies rotate. API-only runs
+  never launch Chromium at all.
+- **Table rendering** (`render.tables`, `core.assets.materialise`). The planner
+  said `table_to_image` and listed the asset ids; nothing produced the files.
+  Tables now render to quantised PNGs at 2x, cached on cell content so a re-run
+  neither re-renders nor re-uploads an unchanged table. The source IR is never
+  mutated — the same document keeps native tables on Dev.to in the same run.
+- `pubkit auth verify <platform>` — check a session before a publish depends on
+  it, rather than discovering it expired halfway through.
+- **Browser integration tests** against a deliberately hostile fixture editor
+  that reproduces multiple content roots, image stripping, figures landing
+  above the caret, and uploads that sit on a `blob:` URL before resolving.
+  They skip cleanly where Chromium is unavailable.
+
+### Fixed
+
+- `marker_regex` was double-escaped, so every `fingerprint()` call threw
+  `SyntaxError: Invalid regular expression` inside the page. Verification was
+  therefore broken on every browser adapter. Found by the new integration
+  tests on their first run.
+- `auth login` routed on a capability flag rather than the platform list, so
+  `pubkit auth login substack` took the API-token path and prompted for a token
+  that does not exist.
+
+## [0.1.1] — 2026-09-11
+
+### Added
+
+- Docker image on the Playwright base (`ghcr.io/arunsingh/pubkit`), so browser
+  adapters work in CI without hand-installing Chromium's system libraries.
+- `action.yml` — the repository is now a reusable GitHub Action.
+- `CITATION.cff`, and a Homebrew formula template under `packaging/`.
+
+### Fixed
+
+- `pubkit doctor` ignored `PLAYWRIGHT_BROWSERS_PATH` and reported Chromium as
+  missing on managed images (CI runners, devcontainers, the Playwright Docker
+  image) where it was in fact installed — sending people off to fix a problem
+  they did not have. Found by running the published package in exactly such an
+  environment.
+
+## [0.1.0] — 2026-09-11
+
+First release. Extracted from a real, painful publishing run: a 15,000-word
+illustrated three-part series to Medium that surfaced 21 distinct failure modes,
+all catalogued in `docs/FAILURE-MODES.md`.
+
+### Added
+
+- **Post IR** — a canonical, platform-agnostic document model with a
+  content-addressed id used as the idempotency key everywhere.
+- **Capability negotiation** — adapters declare what they support; the planner
+  emits explicit, printable degradations. `pubkit plan` shows them before
+  anything is sent.
+- **Check pipeline** — placeholders, numeric assertions, cross-references,
+  number drift, assets, budget, structure. Pluggable via `pubkit.checks`.
+- **Verified chunked transport** — per-chunk rolling-hash verification, probed
+  size ceilings, single-member gzip.
+- **Browser adapter toolkit** — paste-based document replace with a block-count
+  assertion, reload-then-fingerprint verification, caption-anchored `File`
+  image insertion, Unicode-folding anchor resolution, tag-chip post-conditions.
+- **Adapters** — Medium, Substack (browser); X, Dev.to, Hashnode (API).
+- **Runner** — six resumable steps per (document, platform), sqlite state store,
+  two-phase publish for series, hash-pinned `--confirm` gate, per-platform rate
+  limiting and jittered retry.
+- **CLI** — `init`, `validate`, `plan`, `publish`, `status`, `platforms`,
+  `doctor`, `auth login|logout|list`.
+- **Workflows** — GitHub Actions examples and Airflow operators.
+- **Extension points** — `pubkit.adapters`, `pubkit.renderers`, `pubkit.checks`,
+  `pubkit.hooks`, plus per-platform transforms.
+
+### Known limitations
+
+- Browser adapter selectors will need patching when a platform redesigns its
+  editor. They are isolated in one `EditorSelectors` dataclass per adapter
+  precisely so that is a small change.
+- Table→image rendering requires the `render` extra; without it, tables degrade
+  to lists on platforms that lack table support.
+- X media upload uses the v1.1 endpoint, which is what the v2 API still
+  requires.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pubkit
-Version: 0.1.1
+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
@@ -109,9 +109,10 @@ pubkit validate content/series/
 # 2. See exactly what each platform will get — including every degradation.
 pubkit plan content/series/ --to medium,devto,x
 
-# 3. Sign in. pubkit never accepts a password.
-pubkit auth login medium        # opens a window; you sign in; it keeps the session
+# 3. Sign in, once. pubkit never accepts a password.
+pubkit auth login medium        # a window opens; you sign in; it keeps the session
 pubkit auth login devto         # API token → OS keychain
+pubkit auth verify medium       # confirm before a publish depends on it
 
 # 4. Drafts everywhere. Safe to re-run; a dropped connection costs one step.
 pubkit publish content/series/ --to medium,devto,x
@@ -138,6 +139,64 @@ x: part-1 (bf9abfe78ce4)
 
 Nothing is a surprise at publish time. That is the whole design goal.
 
+## Sign in once, then it runs on its own
+
+```bash
+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.
+
+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:
+
+```bash
+pubkit publish content/ --to medium,devto,x --confirm
+```
+
+One browser serves the whole run, one context per platform so a Medium session
+is never presented to Substack, and sessions refresh on the way out because
+cookies rotate. Publishing only to API platforms never launches Chromium at all.
+
+pubkit sees cookies. It never sees, types or stores a password — which is both
+the right security posture and the only thing that works, since platforms
+increasingly gate login behind challenges an automation layer has no business
+trying to defeat.
+
 ## Write once
 
 ````markdown
@@ -287,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.1.1 → pubkit-0.3.0}/README.md

@@ -59,9 +59,10 @@ pubkit validate content/series/
 # 2. See exactly what each platform will get — including every degradation.
 pubkit plan content/series/ --to medium,devto,x
 
-# 3. Sign in. pubkit never accepts a password.
-pubkit auth login medium        # opens a window; you sign in; it keeps the session
+# 3. Sign in, once. pubkit never accepts a password.
+pubkit auth login medium        # a window opens; you sign in; it keeps the session
 pubkit auth login devto         # API token → OS keychain
+pubkit auth verify medium       # confirm before a publish depends on it
 
 # 4. Drafts everywhere. Safe to re-run; a dropped connection costs one step.
 pubkit publish content/series/ --to medium,devto,x
@@ -88,6 +89,64 @@ x: part-1 (bf9abfe78ce4)
 
 Nothing is a surprise at publish time. That is the whole design goal.
 
+## Sign in once, then it runs on its own
+
+```bash
+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.
+
+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:
+
+```bash
+pubkit publish content/ --to medium,devto,x --confirm
+```
+
+One browser serves the whole run, one context per platform so a Medium session
+is never presented to Substack, and sessions refresh on the way out because
+cookies rotate. Publishing only to API platforms never launches Chromium at all.
+
+pubkit sees cookies. It never sees, types or stores a password — which is both
+the right security posture and the only thing that works, since platforms
+increasingly gate login behind challenges an automation layer has no business
+trying to defeat.
+
 ## Write once
 
 ````markdown
@@ -237,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.1.1 → 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.1.1 → pubkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pubkit"
-version = "0.1.1"
+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.1.1 → 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.1.1"
+__version__ = "0.3.0"
 __all__ = [
     "Document", "Series", "Asset", "Figure", "Table", "Heading", "Paragraph", "Code",
     "Pipeline", "RunReport", "load_document", "load_series",

{pubkit-0.1.1 → pubkit-0.3.0}/src/pubkit/adapters/medium.py

@@ -68,7 +68,7 @@ class MediumAdapter(BrowserAdapter):
 
     login_url = "https://medium.com/m/signin"
     new_story_url = "https://medium.com/new-story"
-    marker_regex = r"\\[\\[\\s*IMAGE"
+    marker_regex = r"\[\[\s*IMAGE"
 
     def __init__(self, page=None, upload=None) -> None:
         super().__init__()