pubkit 0.1.0__py3-none-any.whl

pubkit/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""pubkit — publish one source to many platforms, safely."""
+from .core.ir import Asset, Code, Document, Figure, Heading, Paragraph, Series, Table  # noqa: F401
+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.0"
+__all__ = [
+    "Document", "Series", "Asset", "Figure", "Table", "Heading", "Paragraph", "Code",
+    "Pipeline", "RunReport", "load_document", "load_series",
+    "build_adapter", "register", "list_adapters", "__version__",
+]

pubkit/__main__.py

@@ -0,0 +1,7 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Allow `python -m pubkit` as well as the `pubkit` console script."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

pubkit/adapters/__init__.py

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

pubkit/adapters/api_base.py

@@ -0,0 +1,67 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""ApiAdapter — the easy half.
+
+API platforms are pleasant by comparison: no DOM, no editor model, no stripped
+images. What they do have is rate limits, partial failure and the same
+idempotency problem, so the base class handles those and nothing else.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from ..core.adapter import AdapterError, BaseAdapter, Context, RateLimited
+
+log = logging.getLogger(__name__)
+
+
+class ApiAdapter(BaseAdapter):
+    base_url: str = ""
+    timeout: float = 30.0
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._client: httpx.AsyncClient | None = None
+
+    def headers(self, ctx: Context) -> dict[str, str]:  # pragma: no cover - overridden
+        return {}
+
+    async def client(self, ctx: Context) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=self.timeout,
+                headers={"user-agent": "pubkit/0.1 (+https://github.com/arunsingh/pubkit)", **self.headers(ctx)},
+            )
+        return self._client
+
+    async def request(self, ctx: Context, method: str, url: str, **kw: Any) -> httpx.Response:
+        await self.bucket.acquire()
+        client = await self.client(ctx)
+        resp = await client.request(method, url, **kw)
+
+        if resp.status_code == 429:
+            retry = float(resp.headers.get("retry-after", 30))
+            # x-rate-limit-reset is an epoch, not a delta — a detail worth
+            # getting right, because treating it as a delta means sleeping
+            # until roughly 2056.
+            reset = resp.headers.get("x-rate-limit-reset")
+            if reset:
+                import time
+
+                retry = max(1.0, float(reset) - time.time())
+            raise RateLimited(retry)
+
+        if resp.status_code >= 500:
+            raise AdapterError(f"{self.name}: {resp.status_code} from {url}")
+        if resp.status_code >= 400:
+            raise AdapterError(f"{self.name}: {resp.status_code} {resp.text[:300]}")
+        return resp
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None

pubkit/adapters/devto.py

@@ -0,0 +1,195 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Dev.to and Hashnode.
+
+These two exist partly for their own sake and partly as proof that the adapter
+interface is genuinely platform-agnostic: same IR, same checks, same runner,
+about 80 lines each, and native tables and code fences with zero degradation.
+
+Both expect images to already be at public URLs, so they pair with an asset
+host (`pubkit.assets`) rather than uploading through an editor.
+"""
+from __future__ import annotations
+
+import logging
+
+from ..core.adapter import Context, Fingerprint, PublishedRef, RemoteRef
+from ..core.capabilities import Capabilities, TagSpec, select_tags
+from ..core.ir import Document
+from ..render.html import MarkdownRenderer
+from .api_base import ApiAdapter
+
+log = logging.getLogger(__name__)
+
+
+class DevToAdapter(ApiAdapter):
+    name = "devto"
+    base_url = "https://dev.to/api"
+    rate = 0.5
+    burst = 3
+
+    capabilities = Capabilities(
+        tables=True,
+        code_blocks="highlighted",
+        inline_html=True,
+        animated_gif=True,
+        headings=6,
+        image_upload="api",
+        canonical_url=True,
+        tags=TagSpec(max_count=4, max_len=20, strategy="api"),
+        drafts=True,
+    )
+
+    def __init__(self, asset_urls: dict[str, str] | None = None) -> None:
+        super().__init__()
+        self.asset_urls = asset_urls or {}
+        self.renderer = MarkdownRenderer(image_url_for=self.asset_urls.get)
+
+    def headers(self, ctx: Context) -> dict[str, str]:
+        return {"api-key": ctx.tokens.require(self.name), "content-type": "application/json"}
+
+    async def authenticate(self, ctx: Context) -> None:
+        await self.request(ctx, "GET", "/users/me")
+
+    async def ensure_draft(self, doc: Document, ctx: Context) -> RemoteRef:
+        existing = ctx.options.get("remote_ref")
+        if existing:
+            return RemoteRef(id=str(existing))
+        body = {
+            "article": {
+                "title": doc.title,
+                "published": False,
+                "body_markdown": self.renderer.render(doc),
+                "tags": [t.replace(" ", "").lower() for t in select_tags(doc.tags, self.capabilities.tags)],
+                "canonical_url": doc.canonical_url,
+                "description": doc.subtitle or "",
+            }
+        }
+        r = await self.request(ctx, "POST", "/articles", json=body)
+        data = r.json()
+        return RemoteRef(id=str(data["id"]), url=data.get("url"))
+
+    async def push_content(self, doc, plan, ref, ctx) -> None:
+        body = {
+            "article": {
+                "title": doc.title,
+                "body_markdown": self.renderer.render(doc),
+                "tags": [t.replace(" ", "").lower() for t in select_tags(doc.tags, self.capabilities.tags)],
+                "canonical_url": doc.canonical_url,
+                "description": doc.subtitle or "",
+            }
+        }
+        await self.request(ctx, "PUT", f"/articles/{ref.id}", json=body)
+
+    async def verify(self, doc, plan, ref, ctx) -> Fingerprint:
+        r = await self.request(ctx, "GET", f"/articles/{ref.id}")
+        md = r.json().get("body_markdown", "")
+        return Fingerprint(
+            words=len(md.split()),
+            headings=[ln.lstrip("# ").strip()[:48] for ln in md.splitlines() if ln.startswith("#")],
+            images=md.count("!["),
+            links=md.count("]("),
+            markers=md.count("[[ IMAGE"),
+        )
+
+    async def publish(self, doc, ref, ctx) -> PublishedRef:
+        self.guard_publish(ctx)
+        r = await self.request(ctx, "PUT", f"/articles/{ref.id}", json={"article": {"published": True}})
+        data = r.json()
+        return PublishedRef(id=str(ref.id), url=data["url"])
+
+
+class HashnodeAdapter(ApiAdapter):
+    name = "hashnode"
+    base_url = "https://gql.hashnode.com"
+    rate = 1.0
+    burst = 5
+
+    capabilities = Capabilities(
+        tables=True,
+        code_blocks="highlighted",
+        inline_html=True,
+        animated_gif=True,
+        headings=6,
+        image_upload="api",
+        canonical_url=True,
+        tags=TagSpec(max_count=5, max_len=30, strategy="api"),
+        drafts=True,
+    )
+
+    def __init__(self, publication_id: str = "", asset_urls: dict[str, str] | None = None) -> None:
+        super().__init__()
+        self.publication_id = publication_id
+        self.renderer = MarkdownRenderer(image_url_for=(asset_urls or {}).get)
+
+    def headers(self, ctx: Context) -> dict[str, str]:
+        return {"authorization": ctx.tokens.require(self.name), "content-type": "application/json"}
+
+    async def _gql(self, ctx: Context, query: str, variables: dict) -> dict:
+        r = await self.request(ctx, "POST", "/", json={"query": query, "variables": variables})
+        payload = r.json()
+        if payload.get("errors"):
+            from ..core.adapter import AdapterError
+
+            raise AdapterError(f"hashnode: {payload['errors'][0].get('message')}")
+        return payload["data"]
+
+    async def authenticate(self, ctx: Context) -> None:
+        await self._gql(ctx, "query { me { id username } }", {})
+
+    async def ensure_draft(self, doc: Document, ctx: Context) -> RemoteRef:
+        existing = ctx.options.get("remote_ref")
+        if existing:
+            return RemoteRef(id=str(existing))
+        q = """
+        mutation CreateDraft($input: CreateDraftInput!) {
+          createDraft(input: $input) { draft { id slug } }
+        }"""
+        data = await self._gql(
+            ctx,
+            q,
+            {
+                "input": {
+                    "title": doc.title,
+                    "subtitle": doc.subtitle or "",
+                    "contentMarkdown": self.renderer.render(doc),
+                    "publicationId": self.publication_id,
+                    "tags": [{"name": t, "slug": t.lower().replace(" ", "-")} for t in select_tags(doc.tags, self.capabilities.tags)],
+                    "originalArticleURL": doc.canonical_url,
+                }
+            },
+        )
+        draft = data["createDraft"]["draft"]
+        return RemoteRef(id=draft["id"])
+
+    async def push_content(self, doc, plan, ref, ctx) -> None:
+        q = """
+        mutation UpdateDraft($input: UpdateDraftInput!) {
+          updateDraft(input: $input) { draft { id } }
+        }"""
+        await self._gql(
+            ctx,
+            q,
+            {"input": {"id": ref.id, "title": doc.title, "contentMarkdown": self.renderer.render(doc)}},
+        )
+
+    async def verify(self, doc, plan, ref, ctx) -> Fingerprint:
+        data = await self._gql(ctx, "query D($id: ObjectId!) { draft(id: $id) { content { markdown } } }", {"id": ref.id})
+        md = data["draft"]["content"]["markdown"]
+        return Fingerprint(
+            words=len(md.split()),
+            headings=[ln.lstrip("# ").strip()[:48] for ln in md.splitlines() if ln.startswith("#")],
+            images=md.count("!["),
+            links=md.count("]("),
+            markers=md.count("[[ IMAGE"),
+        )
+
+    async def publish(self, doc, ref, ctx) -> PublishedRef:
+        self.guard_publish(ctx)
+        q = """
+        mutation Publish($input: PublishDraftInput!) {
+          publishDraft(input: $input) { post { id url } }
+        }"""
+        data = await self._gql(ctx, q, {"input": {"draftId": ref.id}})
+        post = data["publishDraft"]["post"]
+        return PublishedRef(id=post["id"], url=post["url"])

pubkit/adapters/medium.py

@@ -0,0 +1,184 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Medium.
+
+Medium retired public API tokens for new users, so this is a browser adapter.
+It encodes, in order, every trap found while publishing a 15,000-word
+illustrated three-part series:
+
+  * no table support at all → tables are pre-rendered to figures by the planner
+  * pasted HTML has every image stripped, `data:` and `https:` alike
+  * the only working image path is a synthetic File paste into the editor
+  * the figure lands above the caret's paragraph, so captions are the anchors
+  * DOM edits to links never persist; content must be right before it is sent
+  * the topics field will accept one 40-character invalid tag without complaint
+  * a delete that looks applied can be gone after a reload
+
+Everything is verified after a reload before anything is published.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+
+from ..core.adapter import Context, Fingerprint, PublishedRef, RemoteRef
+from ..core.browser import BrowserAdapter, EditorSelectors
+from ..core.capabilities import Capabilities, TagSpec, select_tags
+from ..core.ir import Document
+from ..render.html import EditorHtmlRenderer
+
+log = logging.getLogger(__name__)
+
+
+class MediumAdapter(BrowserAdapter):
+    name = "medium"
+    rate = 0.5
+    burst = 2
+
+    capabilities = Capabilities(
+        tables=False,                  # the single biggest constraint
+        code_blocks="plain",
+        inline_html=False,
+        animated_gif=True,             # GIFs autoplay inline, which is why
+                                       # animations survive as GIFs
+        headings=4,                    # h3/h4 only inside the body
+        max_body_chars=None,
+        image_upload="browser_paste",
+        canonical_url=True,
+        tags=TagSpec(max_count=5, max_len=25, strategy="comma"),
+        scheduling=True,
+        drafts=True,
+    )
+
+    selectors = EditorSelectors(
+        editable='.postArticle-content[contenteditable="true"]',
+        # ALL section roots. Using only the first is what turned a replace into
+        # an append and produced a scrambled, duplicated draft.
+        content_roots=".section-inner",
+        block=".graf",
+        figure="figure",
+        figure_img="figure img",
+        link="a",
+        publish_button='button[data-action="show-publish-flow"], [data-testid="publishButton"]',
+        tag_input='input[placeholder*="topic" i], input[data-testid="topicInput"]',
+        tag_chip='[data-testid="topicChip"], .js-tagToken',
+        confirm_publish='button:has-text("Publish now")',
+    )
+
+    login_url = "https://medium.com/m/signin"
+    new_story_url = "https://medium.com/new-story"
+    marker_regex = r"\\[\\[\\s*IMAGE"
+
+    def __init__(self, page=None, upload=None) -> None:
+        super().__init__()
+        self._page = page
+        self._upload = upload
+        self.renderer = EditorHtmlRenderer(heading_offset=2, max_heading=4)
+
+    # ------------------------------------------------------------------ auth
+    async def authenticate(self, ctx: Context) -> None:
+        """Session-based. pubkit never sees a password.
+
+        `pubkit auth login medium` opens a visible window, the user signs in,
+        and the resulting storage_state is what gets persisted.
+        """
+        state = ctx.sessions.load(self.name)
+        if state is None:
+            raise RuntimeError(
+                "no saved Medium session. Run `pubkit auth login medium` — "
+                "a browser window opens, you sign in yourself, pubkit stores "
+                "only the session cookie."
+            )
+        await self._page.goto("https://medium.com/me/stories/drafts", wait_until="domcontentloaded")
+        if "signin" in self._page.url:
+            ctx.sessions.forget(self.name)
+            raise RuntimeError("saved Medium session has expired; run `pubkit auth login medium`")
+
+    # ----------------------------------------------------------------- draft
+    async def ensure_draft(self, doc: Document, ctx: Context) -> RemoteRef:
+        """Reuse the recorded draft if there is one; never create a duplicate."""
+        existing = ctx.options.get("remote_ref")
+        if existing:
+            await self._page.goto(f"https://medium.com/p/{existing}/edit", wait_until="domcontentloaded")
+            await asyncio.sleep(3)
+            await self.install_helpers()
+            return RemoteRef(id=existing, url=f"https://medium.com/p/{existing}")
+
+        await self._page.goto(self.new_story_url, wait_until="domcontentloaded")
+        await asyncio.sleep(4)
+        await self.install_helpers()
+        m = re.search(r"/p/([0-9a-f]{8,})/edit", self._page.url)
+        if not m:
+            # A brand-new story gets its id on first save; nudge the editor.
+            await self._page.click(self.selectors.editable)
+            await self._page.keyboard.type(doc.title[:8])
+            await asyncio.sleep(3)
+            m = re.search(r"/p/([0-9a-f]{8,})/edit", self._page.url)
+        if not m:
+            raise RuntimeError(f"could not determine draft id from {self._page.url}")
+        return RemoteRef(id=m.group(1), url=f"https://medium.com/p/{m.group(1)}")
+
+    # --------------------------------------------------------------- content
+    async def push_content(self, doc, plan, ref, ctx) -> None:
+        """One paste for the whole document, with the link targets already
+        correct.
+
+        Links must be right *before* transmission: setting an href in the DOM
+        afterwards looks like it worked and is gone on the next reload, because
+        the editor syncs from its own model (failure B4).
+        """
+        html = self.renderer.render(doc)
+        if "URL-PART" in html or "${" in html:
+            raise RuntimeError(
+                "unresolved cross-reference placeholder in rendered HTML — "
+                "run phase 1 of the two-phase publish first"
+            )
+        await self.install_helpers()
+        await self.replace_document(html)
+
+    # ----------------------------------------------------------------- media
+    async def push_media(self, doc, plan, ref, ctx) -> None:
+        anchors = self.renderer.caption_anchors(doc)
+        if not anchors:
+            return
+        paths = [doc.assets[aid].path for aid, _ in anchors]
+        await self.stage_files(paths, self._upload)
+
+        used: set[int] = set()
+        for i, (asset_id, caption) in enumerate(anchors):
+            await self.bucket.acquire()
+            await self.insert_image_at(caption, i, used=used)
+            log.info("medium: placed %s above %r", asset_id, caption[:48])
+
+    # ---------------------------------------------------------------- verify
+    async def verify(self, doc, plan, ref, ctx) -> Fingerprint:
+        expected = Fingerprint(
+            words=doc.word_count,
+            headings=[],
+            images=len(doc.figures),
+            links=0,
+        )
+
+        async def reload():
+            await self._page.goto(f"https://medium.com/p/{ref.id}/edit", wait_until="domcontentloaded")
+
+        return await self.verify_after_reload(expected, reload)
+
+    # --------------------------------------------------------------- publish
+    async def publish(self, doc, ref, ctx) -> PublishedRef:
+        self.guard_publish(ctx)
+        await self._page.goto(f"https://medium.com/p/{ref.id}/edit", wait_until="domcontentloaded")
+        await asyncio.sleep(3)
+        await self._page.click(self.selectors.publish_button)
+        await asyncio.sleep(3)
+
+        tags = select_tags(doc.tags, self.capabilities.tags)
+        await self.apply_tags(tags, self.capabilities.tags.strategy)
+
+        await self._page.click(self.selectors.confirm_publish)
+        await self._page.wait_for_url(re.compile(r"medium\.com/(@|p/)"), timeout=60_000)
+        await asyncio.sleep(2)
+        url = self._page.url.split("?")[0]
+        log.info("medium: published %s", url)
+        return PublishedRef(id=ref.id, url=url)

pubkit/adapters/substack.py

@@ -0,0 +1,136 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Substack.
+
+No public write API, so this is a browser adapter — and the point of it being
+only ~120 lines is that everything genuinely hard already lives in
+`BrowserAdapter`. Substack's editor (ProseMirror) differs from Medium's in its
+selectors and in accepting real tables; it does not differ in any of the ways
+that caused actual pain.
+
+What is Substack-specific:
+  * ProseMirror node selectors instead of Medium's `.graf`
+  * native tables, so no table→image degradation
+  * publish is a two-step dialog with an email-subscribers choice that must be
+    made explicitly rather than left to the default
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+
+from ..core.adapter import Context, Fingerprint, PublishedRef, RemoteRef
+from ..core.browser import BrowserAdapter, EditorSelectors
+from ..core.capabilities import Capabilities
+from ..core.ir import Document
+from ..render.html import EditorHtmlRenderer
+
+log = logging.getLogger(__name__)
+
+
+class SubstackAdapter(BrowserAdapter):
+    name = "substack"
+    rate = 0.5
+    burst = 2
+
+    capabilities = Capabilities(
+        tables=True,
+        code_blocks="fenced",
+        inline_html=True,
+        animated_gif=True,
+        headings=4,
+        image_upload="browser_paste",
+        canonical_url=True,
+        tags=None,
+        scheduling=True,
+        drafts=True,
+    )
+
+    selectors = EditorSelectors(
+        editable='div[contenteditable="true"].ProseMirror',
+        content_roots="div.ProseMirror",
+        block="div.ProseMirror > *",
+        figure="figure, div[data-attrs*='image']",
+        figure_img="img",
+        link="a",
+        publish_button='button:has-text("Continue")',
+        tag_input=None,
+        tag_chip=None,
+        confirm_publish='button:has-text("Send to everyone now"), button:has-text("Publish now")',
+    )
+
+    def __init__(self, publication: str, page=None, upload=None) -> None:
+        super().__init__()
+        self.publication = publication.rstrip("/")
+        self._page = page
+        self._upload = upload
+        # Substack renders tables natively, so the heading offset is smaller
+        # and tables stay tables.
+        self.renderer = EditorHtmlRenderer(heading_offset=1, max_heading=4)
+
+    async def authenticate(self, ctx: Context) -> None:
+        if ctx.sessions.load(self.name) is None:
+            raise RuntimeError(
+                "no saved Substack session. Run `pubkit auth login substack` "
+                "and sign in yourself in the window that opens."
+            )
+        await self._page.goto(f"{self.publication}/publish/posts", wait_until="domcontentloaded")
+        if "/sign-in" in self._page.url:
+            ctx.sessions.forget(self.name)
+            raise RuntimeError("saved Substack session expired; run `pubkit auth login substack`")
+
+    async def ensure_draft(self, doc: Document, ctx: Context) -> RemoteRef:
+        existing = ctx.options.get("remote_ref")
+        if existing:
+            await self._page.goto(f"{self.publication}/publish/post/{existing}", wait_until="domcontentloaded")
+        else:
+            await self._page.goto(f"{self.publication}/publish/post?type=newsletter", wait_until="domcontentloaded")
+        await asyncio.sleep(4)
+        await self.install_helpers()
+        m = re.search(r"/publish/post/(\d+)", self._page.url)
+        if not m:
+            raise RuntimeError(f"could not determine Substack draft id from {self._page.url}")
+        return RemoteRef(id=m.group(1), url=f"{self.publication}/publish/post/{m.group(1)}")
+
+    async def push_content(self, doc, plan, ref, ctx) -> None:
+        await self._page.fill('input[placeholder*="Title" i]', doc.title)
+        if doc.subtitle:
+            await self._page.fill('textarea[placeholder*="subtitle" i], input[placeholder*="subtitle" i]', doc.subtitle)
+        await self.install_helpers()
+        await self.replace_document(self.renderer.render(doc))
+
+    async def push_media(self, doc, plan, ref, ctx) -> None:
+        anchors = self.renderer.caption_anchors(doc)
+        if not anchors:
+            return
+        await self.stage_files([doc.assets[a].path for a, _ in anchors], self._upload)
+        used: set[int] = set()
+        for i, (asset_id, caption) in enumerate(anchors):
+            await self.bucket.acquire()
+            await self.insert_image_at(caption, i, used=used)
+            log.info("substack: placed %s", asset_id)
+
+    async def verify(self, doc, plan, ref, ctx) -> Fingerprint:
+        expected = Fingerprint(words=doc.word_count, headings=[], images=len(doc.figures), links=0)
+
+        async def reload():
+            await self._page.goto(f"{self.publication}/publish/post/{ref.id}", wait_until="domcontentloaded")
+
+        return await self.verify_after_reload(expected, reload)
+
+    async def publish(self, doc, ref, ctx) -> PublishedRef:
+        self.guard_publish(ctx)
+        await self._page.goto(f"{self.publication}/publish/post/{ref.id}", wait_until="domcontentloaded")
+        await asyncio.sleep(3)
+        await self._page.click(self.selectors.publish_button)
+        await asyncio.sleep(2)
+        # The email choice is explicit on purpose: silently mailing a few
+        # thousand subscribers is not a sensible default for an automation tool.
+        if ctx.options.get("email_subscribers", False):
+            await self._page.click('button:has-text("Send to everyone now")')
+        else:
+            await self._page.click('button:has-text("Publish now")')
+        await asyncio.sleep(5)
+        url = f"{self.publication}/p/{ctx.options.get('slug', ref.id)}"
+        return PublishedRef(id=ref.id, url=url)