pubkit 0.1.0__py3-none-any.whl

pubkit/adapters/x.py

@@ -0,0 +1,216 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""X / Twitter, API v2.
+
+The interesting problem here is not the API, it is that a 6,000-word article
+and a 280-character post are different media. The ThreadRenderer does the
+splitting; this adapter deals with the parts that bite:
+
+  * media upload still lives on the v1.1 host and needs its own flow
+  * `x-rate-limit-reset` is an epoch, not a delta
+  * a thread is a chain — a failure at tweet 7 of 11 leaves a visible,
+    half-finished thread, so the chain is checkpointed per tweet and resumable
+  * posting is irreversible and instantly public, so the publish guard matters
+    more here than anywhere else
+"""
+from __future__ import annotations
+
+import base64
+import logging
+from pathlib import Path
+
+from ..core.adapter import AdapterError, Context, Fingerprint, PublishedRef, RemoteRef
+from ..core.capabilities import Capabilities
+from ..core.ir import Document
+from ..render.html import ThreadRenderer, plain
+from .api_base import ApiAdapter
+
+log = logging.getLogger(__name__)
+
+
+class XAdapter(ApiAdapter):
+    name = "x"
+    base_url = "https://api.twitter.com"
+    rate = 0.2          # v2 free/basic tiers are stingy; be a good citizen
+    burst = 2
+
+    capabilities = Capabilities(
+        tables=False,
+        code_blocks="none",
+        inline_html=False,
+        animated_gif=True,
+        headings=1,
+        max_body_chars=280,
+        # promo mode never needs more than max_posts; see __init__.
+        image_upload="api",
+        canonical_url=False,
+        tags=None,           # hashtags are body text here, not metadata
+        threads=True,
+        drafts=False,        # no draft concept — publish is one-shot
+    )
+
+    def __init__(self, limit: int = 280, mode: str = "promo", max_posts: int = 12) -> None:
+        """`mode`:
+
+        promo (default)
+            A hook, three or four of the article's sharpest claims, and a link.
+            This is what actually works on X, and it is what a long-form author
+            wants: the article lives on the blog, the thread sells it.
+
+        full
+            Serialise the whole body. Honest, occasionally right, usually a
+            180-tweet wall nobody reads. Opt in deliberately.
+        """
+        super().__init__()
+        self.mode = mode
+        self.max_posts = max_posts
+        self.renderer = ThreadRenderer(limit=limit)
+
+    def refine_plan(self, doc: Document, p):
+        """promo mode summarises rather than serialises, so the generic
+        'body is too long' degradation is simply wrong here."""
+        from ..core.capabilities import Degradation, DegradationKind
+
+        if self.mode != "promo":
+            return p
+        n = len(self._thread(doc))
+        p.degradations = [
+            d for d in p.degradations
+            if d.kind not in (DegradationKind.SPLIT_INTO_THREAD, DegradationKind.CODE_FLATTENED,
+                              DegradationKind.HEADINGS_CLAMPED)
+        ]
+        p.blocking = [b for b in p.blocking if "body is" not in b]
+        p.degradations.insert(0, Degradation(
+            kind=DegradationKind.SPLIT_INTO_THREAD,
+            detail=f"promo thread: {n} posts — hook, key claims, link to the full article",
+            count=n,
+        ))
+        p.estimated_body_chars = sum(len(t) for t in self._thread(doc))
+        return p
+
+    def headers(self, ctx: Context) -> dict[str, str]:
+        return {
+            "authorization": f"Bearer {ctx.tokens.require(self.name, 'bearer')}",
+            "content-type": "application/json",
+        }
+
+    async def authenticate(self, ctx: Context) -> None:
+        await self.request(ctx, "GET", "/2/users/me")
+
+    def _thread(self, doc: Document) -> list[str]:
+        if self.mode == "full":
+            return self.renderer.render(doc)[: self.max_posts * 4]
+        return self._promo(doc)
+
+    def _promo(self, doc: Document) -> list[str]:
+        """Hook, the strongest claims, then the link."""
+        from ..core.ir import Callout, ListBlock, Paragraph
+
+        link = doc.canonical_url or ""
+        posts: list[str] = []
+
+        opener = doc.subtitle or next(
+            (b.text for b in doc.blocks if isinstance(b, Paragraph)), doc.title
+        )
+        posts.append(f"{doc.title}\n\n{plain(opener)}"[:265])
+
+        # Callouts and short standalone list items are the claims an author
+        # already marked as load-bearing; they make far better tweets than
+        # arbitrary paragraph slices.
+        claims: list[str] = []
+        for b in doc.blocks:
+            if isinstance(b, Callout):
+                claims.append(plain(b.text))
+            elif isinstance(b, ListBlock):
+                claims.extend(plain(i) for i in b.items if 40 <= len(i) <= 230)
+            if len(claims) >= self.max_posts - 2:
+                break
+        for c in claims[: self.max_posts - 2]:
+            posts.append(c[:265])
+
+        posts.append(("Full write-up: " + link).strip() if link else "Full write-up in the replies.")
+        total = len(posts)
+        return [f"{p} ({i+1}/{total})" if total > 1 else p for i, p in enumerate(posts)]
+
+    async def ensure_draft(self, doc: Document, ctx: Context) -> RemoteRef:
+        # No drafts on this platform. The "draft" is the rendered thread, which
+        # we hold locally so `plan` can show it before anything is posted.
+        return RemoteRef(id=f"local:{doc.content_id[:12]}", extra={"thread": self._thread(doc)})
+
+    async def push_content(self, doc, plan, ref, ctx) -> None:
+        ref.extra["thread"] = self._thread(doc)
+
+    async def push_media(self, doc, plan, ref, ctx) -> None:
+        """Upload the first few figures and pin them to early tweets.
+
+        Deliberately not all of them: a thread where every tweet carries an
+        image reads as a slideshow and performs worse than one good visual on
+        the opening post.
+        """
+        figures = doc.figures[:4]
+        media_ids: list[str] = []
+        for fig in figures:
+            asset = doc.assets[fig.asset_id]
+            media_ids.append(await self._upload_media(ctx, asset.path))
+        ref.extra["media_ids"] = media_ids
+
+    async def _upload_media(self, ctx: Context, path: Path) -> str:
+        data = base64.b64encode(path.read_bytes()).decode()
+        await self.bucket.acquire()
+        client = await self.client(ctx)
+        r = await client.post(
+            "https://upload.twitter.com/1.1/media/upload.json",
+            data={"media_data": data},
+            headers={"authorization": client.headers["authorization"]},
+        )
+        if r.status_code >= 400:
+            raise AdapterError(f"x: media upload failed {r.status_code} {r.text[:200]}")
+        return str(r.json()["media_id_string"])
+
+    async def verify(self, doc, plan, ref, ctx) -> Fingerprint:
+        thread = ref.extra.get("thread", [])
+        over = [i for i, t in enumerate(thread) if len(t) > 280]
+        if over:
+            raise AdapterError(f"tweets {over} exceed 280 characters after rendering")
+        return Fingerprint(
+            words=sum(len(t.split()) for t in thread),
+            headings=[],
+            images=len(ref.extra.get("media_ids", [])),
+            links=sum(t.count("http") for t in thread),
+        )
+
+    async def publish(self, doc, ref, ctx) -> PublishedRef:
+        """Post the chain, checkpointing after every tweet.
+
+        If tweet 7 of 11 fails, the already-posted 6 are recorded so a resumed
+        run continues the chain instead of starting a second one beside it.
+        """
+        self.guard_publish(ctx)
+        thread: list[str] = ref.extra["thread"]
+        media_ids: list[str] = ref.extra.get("media_ids", [])
+        posted: list[str] = ref.extra.setdefault("posted", [])
+
+        reply_to = posted[-1] if posted else None
+        first_url = ref.extra.get("first_url")
+
+        for i, text in enumerate(thread):
+            if i < len(posted):
+                continue
+            payload: dict = {"text": text}
+            if reply_to:
+                payload["reply"] = {"in_reply_to_tweet_id": reply_to}
+            if i == 0 and media_ids:
+                payload["media"] = {"media_ids": media_ids[:1]}
+            elif i in (3, 6) and len(media_ids) > 1:
+                payload["media"] = {"media_ids": [media_ids.pop(1)]}
+
+            r = await self.request(ctx, "POST", "/2/tweets", json=payload)
+            tid = r.json()["data"]["id"]
+            posted.append(tid)
+            reply_to = tid
+            if i == 0:
+                first_url = f"https://x.com/i/status/{tid}"
+                ref.extra["first_url"] = first_url
+            log.info("x: posted %d/%d", i + 1, len(thread))
+
+        return PublishedRef(id=posted[0], url=first_url or f"https://x.com/i/status/{posted[0]}")

pubkit/browserctl.py

@@ -0,0 +1,78 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Playwright lifecycle: one browser, many adapters, sessions persisted.
+
+The interactive login flow is the important part. pubkit opens a *visible*
+window, the person signs in themselves — password manager, MFA, device
+confirmation, whatever the platform demands — and pubkit saves only the
+resulting storage_state. It never sees, types or stores a password.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Sequence
+from contextlib import asynccontextmanager
+
+from .core.auth import SessionStore
+
+log = logging.getLogger(__name__)
+
+LOGIN_URLS = {
+    "medium": ("https://medium.com/m/signin", "https://medium.com/me/stories/drafts"),
+    "substack": ("https://substack.com/sign-in", "https://substack.com/home"),
+}
+
+
+@asynccontextmanager
+async def browser_page(platform: str, sessions: SessionStore, *, headless: bool = True):
+    from playwright.async_api import async_playwright
+
+    state = sessions.load(platform)
+    async with async_playwright() as pw:
+        browser = await pw.chromium.launch(headless=headless)
+        context = await browser.new_context(
+            storage_state=state,
+            viewport={"width": 1440, "height": 900},
+        )
+        page = await context.new_page()
+        try:
+            yield page, _uploader(page)
+        finally:
+            # Refresh the stored session on the way out: cookies rotate, and a
+            # session that silently expires mid-run is a bad afternoon.
+            try:
+                sessions.save(platform, await context.storage_state())
+            except Exception:  # noqa: BLE001
+                log.debug("could not refresh %s session", platform)
+            await context.close()
+            await browser.close()
+
+
+def _uploader(page):
+    async def upload(selector: str, paths: Sequence[str]) -> None:
+        await page.set_input_files(selector, list(paths))
+    return upload
+
+
+async def interactive_login(platform: str, sessions: SessionStore, timeout: float = 300.0) -> None:
+    from playwright.async_api import async_playwright
+
+    login_url, success_url = LOGIN_URLS.get(platform, ("https://" + platform, "https://" + platform))
+    async with async_playwright() as pw:
+        browser = await pw.chromium.launch(headless=False)
+        context = await browser.new_context(viewport={"width": 1280, "height": 900})
+        page = await context.new_page()
+        await page.goto(login_url)
+        print(f"Sign in to {platform} in the window that opened. Waiting up to {timeout:.0f}s…")
+        deadline = asyncio.get_event_loop().time() + timeout
+        host = success_url.split("/")[2]
+        while asyncio.get_event_loop().time() < deadline:
+            if host in page.url and "sign" not in page.url and "login" not in page.url:
+                await asyncio.sleep(2)
+                sessions.save(platform, await context.storage_state())
+                await browser.close()
+                return
+            await asyncio.sleep(1.5)
+        await browser.close()
+        raise TimeoutError(f"no {platform} login detected within {timeout:.0f}s")

pubkit/cli.py

@@ -0,0 +1,306 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""pubkit CLI."""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table as RichTable
+
+from . import __version__
+from .core.adapter import Context
+from .core.auth import SessionStore, TokenStore
+from .core.capabilities import plan as make_plan
+from .core.checks import run_checks
+from .core.loader import load_document, load_series
+from .core.runner import Pipeline
+from .core.state import StateStore
+from .registry import build_adapter, list_adapters
+
+app = typer.Typer(add_completion=False, help="Publish one source to many platforms, safely.")
+auth_app = typer.Typer(help="Credentials. pubkit never accepts a password.")
+app.add_typer(auth_app, name="auth")
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        Console().print(f"pubkit {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        None, "--version", "-V", callback=_version_callback, is_eager=True, help="Show the version and exit."
+    ),
+) -> None:
+    """Publish one source to many platforms, safely."""
+
+
+def _setup_logging(verbose: bool) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.INFO,
+        format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def _docs(path: Path):
+    if path.is_dir():
+        files = sorted(path.glob("*.md"))
+        if not files:
+            raise typer.BadParameter(f"no .md files in {path}")
+        return load_series(files)
+    return load_document(path)
+
+
+# ---------------------------------------------------------------- validate
+@app.command()
+def validate(
+    path: Path = typer.Argument(..., help="A .md file, or a directory for a series"),
+    strict: bool = typer.Option(False, help="Treat warnings as errors"),
+    verbose: bool = typer.Option(False, "-v"),
+):
+    """Run the check pipeline. No network, no browser, no side effects."""
+    _setup_logging(verbose)
+    target = _docs(path)
+    documents = target.documents if hasattr(target, "documents") else [target]
+
+    failed = False
+    for doc in documents:
+        res = run_checks(doc)
+        console.print(f"\n[bold]{doc.id}[/] — {doc.word_count:,} words, "
+                      f"{len(doc.figures)} figures, {len(doc.tables)} tables")
+        if not res.findings:
+            console.print("  [green]all checks passed[/]")
+        for f in res.findings:
+            colour = {"error": "red", "warn": "yellow", "info": "dim"}[f.severity.value]
+            console.print(f"  [{colour}]{f}[/]")
+        if res.errors or (strict and res.findings):
+            failed = True
+
+    raise typer.Exit(1 if failed else 0)
+
+
+# -------------------------------------------------------------------- plan
+@app.command()
+def plan(
+    path: Path = typer.Argument(...),
+    platforms: str = typer.Option(..., "--to", help="Comma-separated: medium,x,substack,devto"),
+    verbose: bool = typer.Option(False, "-v"),
+):
+    """Show exactly what each platform will get, including every degradation."""
+    _setup_logging(verbose)
+    target = _docs(path)
+    documents = target.documents if hasattr(target, "documents") else [target]
+    names = [p.strip() for p in platforms.split(",") if p.strip()]
+
+    for doc in documents:
+        for name in names:
+            adapter = build_adapter(name)
+            p = make_plan(doc, name, adapter.capabilities, adapter)
+            console.print()
+            console.print(p.human())
+
+    console.print("\n[dim]Nothing has been sent. Use `pubkit publish` to apply.[/]")
+
+
+# ----------------------------------------------------------------- publish
+@app.command()
+def publish(
+    path: Path = typer.Argument(...),
+    platforms: str = typer.Option(..., "--to"),
+    confirm: bool = typer.Option(False, "--confirm", help="Actually publish (not just draft)"),
+    draft_only: bool = typer.Option(False, "--draft-only", help="Create/update drafts and stop"),
+    headless: bool = typer.Option(True, help="Browser adapters run headless"),
+    email_subscribers: bool = typer.Option(False, help="Substack: send the email too"),
+    verbose: bool = typer.Option(False, "-v"),
+):
+    """Create or update drafts and, with --confirm, publish.
+
+    Safe to re-run. A dropped connection costs you one step, not one run.
+    """
+    _setup_logging(verbose)
+    confirm = confirm or os.environ.get("PUBKIT_CONFIRM") == "1"
+    target = _docs(path)
+    names = [p.strip() for p in platforms.split(",") if p.strip()]
+
+    tokens, sessions = TokenStore(), SessionStore()
+    adapters = [build_adapter(n) for n in names]
+
+    def ctx_for(name: str) -> Context:
+        return Context(
+            platform=name,
+            tokens=tokens,
+            sessions=sessions,
+            confirm=confirm and not draft_only,
+            headless=headless,
+            options={"email_subscribers": email_subscribers},
+        )
+
+    pipe = Pipeline(StateStore())
+
+    async def go():
+        if hasattr(target, "documents"):
+            return await pipe.run_series(target, adapters, ctx_for, publish=confirm and not draft_only)
+        return await pipe.run([target], adapters, ctx_for, publish=confirm and not draft_only)
+
+    report = asyncio.run(go())
+    console.print(f"\n[bold]{report.run_id}[/]")
+    console.print(report.human())
+    if not confirm and not draft_only:
+        console.print("\n[yellow]Drafts only — nothing is public. Re-run with --confirm to publish.[/]")
+    raise typer.Exit(0 if report.ok else 1)
+
+
+# ------------------------------------------------------------------ status
+@app.command()
+def status(as_json: bool = typer.Option(False, "--json")):
+    """What exists where, and whether it is published."""
+    store = StateStore()
+    rows = store._conn.execute(
+        "SELECT document_id, platform, url, published, updated_at FROM remotes ORDER BY document_id"
+    ).fetchall()
+    if as_json:
+        print(json.dumps([dict(r) for r in rows], indent=2))
+        return
+    t = RichTable("document", "platform", "state", "url")
+    for r in rows:
+        t.add_row(
+            r["document_id"],
+            r["platform"],
+            "published" if r["published"] else "draft",
+            r["url"] or "",
+        )
+    console.print(t)
+
+
+@app.command()
+def platforms():
+    """List available adapters and what they can do."""
+    t = RichTable("platform", "kind", "tables", "images", "tags", "threads")
+    for name, adapter in list_adapters():
+        c = adapter.capabilities
+        t.add_row(
+            name,
+            "browser" if c.image_upload == "browser_paste" else "api",
+            "yes" if c.tables else "no → images",
+            c.image_upload,
+            f"{c.tags.max_count}×{c.tags.max_len}" if c.tags else "—",
+            "yes" if c.threads else "—",
+        )
+    console.print(t)
+
+
+# -------------------------------------------------------------------- init
+@app.command()
+def init(
+    path: Path = typer.Argument(Path("."), help="Where to scaffold"),
+    series: bool = typer.Option(False, help="Include a two-part series example"),
+    force: bool = typer.Option(False, help="Overwrite existing files"),
+):
+    """Scaffold a content repo that validates on the first try."""
+    from .scaffold import init_repo
+
+    written = init_repo(path, series=series, force=force)
+    if not written:
+        console.print("[yellow]nothing written — files already exist (use --force)[/]")
+        raise typer.Exit(1)
+    for p in written:
+        console.print(f"  [green]+[/] {p}")
+    console.print(
+        f"\nNext:\n"
+        f"  pubkit validate {path / 'content'}\n"
+        f"  pubkit plan {path / 'content'} --to medium,devto\n"
+        f"  pubkit auth login devto"
+    )
+
+
+@app.command()
+def doctor():
+    """Diagnose the environment. Run this before opening an issue."""
+    from .scaffold import diagnose
+
+    findings = diagnose()
+    t = RichTable("", "check", "state")
+    problems = []
+    for f in findings:
+        t.add_row("[green]✓[/]" if f.ok else "[red]✗[/]", f.label, f.detail)
+        if not f.ok and f.fix:
+            problems.append((f.label, f.fix))
+    console.print(t)
+    for label, fix in problems:
+        console.print(f"[yellow]{label}[/]: " + fix.replace("[", "\\["))
+    console.print(f"\npubkit {__version__}")
+
+
+# -------------------------------------------------------------------- auth
+@auth_app.command("login")
+def auth_login(
+    platform: str = typer.Argument(...),
+    token: str = typer.Option(None, "--token", help="API platforms only. Prefer stdin."),
+):
+    """Authenticate.
+
+    API platforms: paste a token (it goes to your OS keychain).
+    Browser platforms: a real browser window opens and you sign in yourself —
+    pubkit stores only the resulting session, never a password.
+    """
+    tokens = TokenStore()
+    adapter = build_adapter(platform)
+
+    if adapter.capabilities.image_upload != "browser_paste" and adapter.name not in ("substack",):
+        if token is None:
+            token = typer.prompt(f"{platform} API token", hide_input=True)
+        tokens.set(platform, token.strip())
+        console.print(f"[green]stored {platform} token in the system keychain[/]")
+        return
+
+    from .browserctl import interactive_login
+
+    console.print(
+        f"Opening a browser window for {platform}. Sign in there — including MFA — "
+        "and pubkit will save the session when it sees you are logged in."
+    )
+    asyncio.run(interactive_login(platform, SessionStore()))
+    console.print(f"[green]saved {platform} session (encrypted)[/]")
+
+
+@auth_app.command("logout")
+def auth_logout(platform: str = typer.Argument(...)):
+    TokenStore().delete(platform)
+    SessionStore().forget(platform)
+    console.print(f"[green]forgot all {platform} credentials[/]")
+
+
+@auth_app.command("list")
+def auth_list():
+    tokens, sessions = TokenStore(), SessionStore()
+    t = RichTable("platform", "token", "session")
+    for name, _ in list_adapters():
+        t.add_row(
+            name,
+            "yes" if tokens.get(name) else "—",
+            "yes" if sessions.exists(name) else "—",
+        )
+    console.print(t)
+
+
+def main() -> None:  # pragma: no cover
+    try:
+        app()
+    except KeyboardInterrupt:
+        console.print("\n[yellow]interrupted — re-run the same command to resume[/]")
+        sys.exit(130)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

pubkit/core/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0