article 0.1.3__tar.gz → 0.1.5__tar.gz

{article-0.1.3 → article-0.1.5}/.env.example

@@ -2,20 +2,20 @@
 # Loaded by article.config.Settings via pydantic-settings.
 # Every platform is optional: omit a platform's secrets to skip it.
 
-# --- Substack (Phase 1, primary) ---------------------------------------------
+# --- Substack (Phase 1, primary; drafts only) ---------------------------------
 # Public URL of your publication; the canonical SSOT URL is derived from it.
 SUBSTACK_PUBLICATION_URL=https://yourname.substack.com
-# Credentials are only needed when no saved browser session exists yet.
-SUBSTACK_EMAIL=you@example.com
+# Auth, first one set wins. The cookie header copied from a logged-in browser:
+SUBSTACK_COOKIES=
+# ... or a JSON file of cookies:
+SUBSTACK_COOKIES_PATH=
+# ... or email + password (accounts that have a password):
+SUBSTACK_EMAIL=
 SUBSTACK_PASSWORD=
-# Where the Playwright storage_state (cookies/session) is persisted/reused.
-SUBSTACK_SESSION_PATH=.article/substack_session.json
 
 # --- Medium (Phase 2) --------------------------------------------------------
-# Self-issued integration token: Settings > Security and apps > Integration tokens.
-# NOTE: Medium's API is deprecated but still works with a self-issued token.
-MEDIUM_TOKEN=
-MEDIUM_USER_ID=
+# Nothing to set: Medium's API is closed to new integrations, so the adapter
+# prints the "Import a story" step instead of posting.
 
 # --- Dev.to / Forem (Phase 2) ------------------------------------------------
 # Generate at https://dev.to/settings/extensions ("DEV API Keys").
@@ -30,6 +30,3 @@ HASHNODE_PUBLICATION_ID=
 # --- Pipeline ----------------------------------------------------------------
 # JSON state store; the canonical_url SSOT lives here, keyed by article slug.
 STATE_PATH=pipeline_state.json
-# Human-like pacing window (seconds) for browser automation.
-MIN_ACTION_DELAY=0.6
-MAX_ACTION_DELAY=2.4

{article-0.1.3 → article-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: article
-Version: 0.1.3
+Version: 0.1.5
 Summary: Tools to semi-automate the publication of articles
 Project-URL: Homepage, https://github.com/thorwhalen/article
 Project-URL: Repository, https://github.com/thorwhalen/article
@@ -22,18 +22,24 @@ Requires-Dist: httpx
 Requires-Dist: pydantic-settings>=2
 Requires-Dist: pydantic>=2
 Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
 Provides-Extra: completion
 Requires-Dist: argcomplete; extra == 'completion'
 Provides-Extra: dev
-Requires-Dist: playwright; extra == 'dev'
+Requires-Dist: pillow; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: python-substack<0.11,>=0.10; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
 Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: images
+Requires-Dist: pillow; extra == 'images'
 Provides-Extra: substack
-Requires-Dist: playwright; extra == 'substack'
+Requires-Dist: markdown-it-py>=3; extra == 'substack'
+Requires-Dist: mdit-py-plugins>=0.4; extra == 'substack'
+Requires-Dist: python-substack<0.11,>=0.10; extra == 'substack'
 Description-Content-Type: text/markdown
 
 # article
@@ -46,9 +52,61 @@ Hashnode) — each pointing its canonical URL back to the primary, so you get
 cross-platform reach without an SEO duplicate-content penalty.
 
 ```bash
-pip install article
+pip install 'article[substack]'
+article draft-substack essay.md            # an UNPUBLISHED Substack draft
 ```
 
+`draft-substack` turns a Markdown file into a Substack draft: `[^n]` footnotes, `![alt](src "caption")` captions, `$...$` LaTeX and local images (uploaded to Substack) all survive. **It never publishes**: you review the draft in the Substack editor and press Publish there. Add `--dry-run` to check and convert without credentials or network.
+
+## Markdown to a Substack draft
+
+The essay is a plain `.md` file. The title is a `title:` in front matter, or else the `# Heading` (removed from the body, since Substack shows the title itself) when there is exactly one, or when the first of several opens the file; the slug is derived from the title unless front matter sets `slug:`. Front matter can also set `subtitle`, `tags` and `description`:
+
+```markdown
+---
+subtitle: Why everyone agrees and nobody agrees
+tags: [agile, ai]
+---
+# The Agile Religion
+
+A claim.[^1]
+
+![The tower of Babel](img/babel.jpg "Bruegel, The Tower of Babel (1563)")
+
+[^1]: The footnote text.
+```
+
+Image paths resolve against the Markdown file's directory. Before anything is uploaded, the command refuses (listing every case, with the line) whatever Substack would silently lose:
+
+| Construct | Why | What to do |
+|---|---|---|
+| A table | Substack has no table node | `--tables code` keeps it as a monospace code block; `--tables image` renders it to a PNG (needs `pip install 'article[images]'`); in Python, `tables=` also takes a function returning the image Markdown |
+| An image in a paragraph with text | the converter keeps only the alt text | give the image its own paragraph; caption goes in the title slot |
+| A missing local image | nothing to upload | fix the path |
+| A raw HTML block | the converter drops it | rewrite it in Markdown |
+| A `data:` image | cannot be uploaded | save it as a file |
+| A footnote that is never referenced, a `[^x]` with no definition, or a reference inside a footnote | dropped, left as text, or misnumbered | fix the reference |
+
+```bash
+article draft-substack essay.md --dry-run          # what survives, no credentials needed
+article draft-substack essay.md                    # create the draft; prints its edit link
+article draft-substack essay.md --tables code      # keep tables as code blocks
+article draft-substack essay.md --update           # rewrite the draft the last run created (refuses if you edited it in Substack; --overwrite-edits to replace those edits)
+article syndicate-secondary essay.md               # refused until the Substack post is live (--allow-unpublished to override)
+```
+
+The draft's future public URL (`<publication>/p/<slug>`) is recorded as the canonical URL, so `syndicate-secondary` can point the other platforms at it.
+
+### Substack credentials
+
+Substack has no official write API; this uses the unofficial [python-substack](https://github.com/ma2za/python-substack) client, which talks to undocumented endpoints that can change. Put one of these in `.env` (never commit it):
+
+- `SUBSTACK_COOKIES`: the cookie header from a logged-in browser session (developer tools, Network tab, any `substack.com` request, the `cookie` request header). The most reliable route, since sign-in by email link or captcha cannot be scripted.
+- `SUBSTACK_COOKIES_PATH`: a JSON file of cookies (`{"substack.sid": "...", ...}`).
+- `SUBSTACK_EMAIL` and `SUBSTACK_PASSWORD`, for accounts with a password.
+
+Set `SUBSTACK_PUBLICATION_URL` (e.g. `https://you.substack.com`) if your account has more than one publication. The live smoke test (`tests/test_substack_live.py`) runs only when these are set; it creates one draft and deletes it.
+
 ## The single source of truth
 
 The Substack public URL captured in phase 1 is the SSOT. It is stored
@@ -65,7 +123,8 @@ author.json ──► publish-primary ──► Substack ──► live URL ─
 ```
 
 The two phases are deliberately separate commands so you can syndicate later
-(e.g. `+3 days`) on your own schedule.
+(e.g. `+3 days`) on your own schedule. Phase 1 creates a Substack **draft**;
+publish it in the Substack editor before syndicating.
 
 ## Two-command flow
 
@@ -85,7 +144,7 @@ After `pip install`, the `article` console script is equivalent
 
 ## The article JSON
 
-One standardized file is the single source of truth for content **and** which
+Instead of a Markdown file, an article can be one JSON file. One standardized file is the single source of truth for content **and** which
 platforms to publish to — a platform is published only if it appears under
 `platforms` (see [`examples/article.example.json`](examples/article.example.json)):
 
@@ -96,7 +155,7 @@ platforms to publish to — a platform is published only if it appears under
   "content_markdown": "# Designing an SSOT Publishing Pipeline\n\n…",
   "tags": ["python", "automation", "seo"],
   "platforms": {
-    "substack": { "publish_as_draft": false },
+    "substack": { "tables": "error" },
     "medium":   { "publish_as_draft": true },
     "dev_to":   { "publish_as_draft": true },
     "hashnode": { "publish_as_draft": true }
@@ -160,7 +219,8 @@ async def publish(article, *, canonical_url, config, secrets):
 | Adapters | `article/adapters/*` | One module per platform (config + secrets injected) |
 | CLI | `article/__main__.py` | `cw` dispatch of the two commands |
 
-> **Status:** the layers above are complete and tested; each adapter's actual
-> network / Playwright call is a clearly-marked `TODO` stub that returns a typed
-> placeholder result. Payload field names are verified against each platform's
-> live API (`canonicalUrl` / `canonical_url` / `originalArticleURL`).
+> **Status, per platform:**
+>
+> - **Substack**: real. Creates unpublished drafts through python-substack; never publishes.
+> - **Medium**: honest manual step. Its API is closed to new integrations, so the adapter sends nothing and reports a `[todo]` result: open Medium's *Import a story* page (https://medium.com/p/import) and paste the published Substack URL, which sets the canonical link.
+> - **Dev.to, Hashnode**: still stubs; they build the payload (with the canonical field) but make no network call.

article-0.1.5/README.md

@@ -0,0 +1,182 @@
+# article
+
+Tools to semi-automate the publication of articles.
+
+Write an article **once** as a JSON file. Publish it to a **primary** platform
+(Substack), then **syndicate** it to secondary platforms (Medium, Dev.to,
+Hashnode) — each pointing its canonical URL back to the primary, so you get
+cross-platform reach without an SEO duplicate-content penalty.
+
+```bash
+pip install 'article[substack]'
+article draft-substack essay.md            # an UNPUBLISHED Substack draft
+```
+
+`draft-substack` turns a Markdown file into a Substack draft: `[^n]` footnotes, `![alt](src "caption")` captions, `$...$` LaTeX and local images (uploaded to Substack) all survive. **It never publishes**: you review the draft in the Substack editor and press Publish there. Add `--dry-run` to check and convert without credentials or network.
+
+## Markdown to a Substack draft
+
+The essay is a plain `.md` file. The title is a `title:` in front matter, or else the `# Heading` (removed from the body, since Substack shows the title itself) when there is exactly one, or when the first of several opens the file; the slug is derived from the title unless front matter sets `slug:`. Front matter can also set `subtitle`, `tags` and `description`:
+
+```markdown
+---
+subtitle: Why everyone agrees and nobody agrees
+tags: [agile, ai]
+---
+# The Agile Religion
+
+A claim.[^1]
+
+![The tower of Babel](img/babel.jpg "Bruegel, The Tower of Babel (1563)")
+
+[^1]: The footnote text.
+```
+
+Image paths resolve against the Markdown file's directory. Before anything is uploaded, the command refuses (listing every case, with the line) whatever Substack would silently lose:
+
+| Construct | Why | What to do |
+|---|---|---|
+| A table | Substack has no table node | `--tables code` keeps it as a monospace code block; `--tables image` renders it to a PNG (needs `pip install 'article[images]'`); in Python, `tables=` also takes a function returning the image Markdown |
+| An image in a paragraph with text | the converter keeps only the alt text | give the image its own paragraph; caption goes in the title slot |
+| A missing local image | nothing to upload | fix the path |
+| A raw HTML block | the converter drops it | rewrite it in Markdown |
+| A `data:` image | cannot be uploaded | save it as a file |
+| A footnote that is never referenced, a `[^x]` with no definition, or a reference inside a footnote | dropped, left as text, or misnumbered | fix the reference |
+
+```bash
+article draft-substack essay.md --dry-run          # what survives, no credentials needed
+article draft-substack essay.md                    # create the draft; prints its edit link
+article draft-substack essay.md --tables code      # keep tables as code blocks
+article draft-substack essay.md --update           # rewrite the draft the last run created (refuses if you edited it in Substack; --overwrite-edits to replace those edits)
+article syndicate-secondary essay.md               # refused until the Substack post is live (--allow-unpublished to override)
+```
+
+The draft's future public URL (`<publication>/p/<slug>`) is recorded as the canonical URL, so `syndicate-secondary` can point the other platforms at it.
+
+### Substack credentials
+
+Substack has no official write API; this uses the unofficial [python-substack](https://github.com/ma2za/python-substack) client, which talks to undocumented endpoints that can change. Put one of these in `.env` (never commit it):
+
+- `SUBSTACK_COOKIES`: the cookie header from a logged-in browser session (developer tools, Network tab, any `substack.com` request, the `cookie` request header). The most reliable route, since sign-in by email link or captcha cannot be scripted.
+- `SUBSTACK_COOKIES_PATH`: a JSON file of cookies (`{"substack.sid": "...", ...}`).
+- `SUBSTACK_EMAIL` and `SUBSTACK_PASSWORD`, for accounts with a password.
+
+Set `SUBSTACK_PUBLICATION_URL` (e.g. `https://you.substack.com`) if your account has more than one publication. The live smoke test (`tests/test_substack_live.py`) runs only when these are set; it creates one draft and deletes it.
+
+## The single source of truth
+
+The Substack public URL captured in phase 1 is the SSOT. It is stored
+(keyed by article slug) and injected as `canonical_url` into every secondary
+platform in phase 2, so each emits `<link rel="canonical" href="…">` pointing
+back at the original.
+
+```
+author.json ──► publish-primary ──► Substack ──► live URL ─┐
+                                                           │ stored as canonical_url
+                                                           ▼  (pipeline_state.json, by slug)
+                          syndicate-secondary ──► Medium / Dev.to / Hashnode
+                                                  each canonical → Substack URL
+```
+
+The two phases are deliberately separate commands so you can syndicate later
+(e.g. `+3 days`) on your own schedule. Phase 1 creates a Substack **draft**;
+publish it in the Substack editor before syndicating.
+
+## Two-command flow
+
+```bash
+# 1. Author once, then publish to the primary (records the canonical URL):
+python -m article publish-primary article.json
+
+# 2. Later — syndicate everywhere, injecting the canonical URL for SEO:
+python -m article syndicate-secondary article.json
+
+# Subset / machine-readable output:
+python -m article syndicate-secondary article.json --platforms medium,dev_to --json-out
+```
+
+After `pip install`, the `article` console script is equivalent
+(`article publish-primary article.json`).
+
+## The article JSON
+
+Instead of a Markdown file, an article can be one JSON file. One standardized file is the single source of truth for content **and** which
+platforms to publish to — a platform is published only if it appears under
+`platforms` (see [`examples/article.example.json`](examples/article.example.json)):
+
+```json
+{
+  "title": "Designing an SSOT Publishing Pipeline",
+  "slug": "ssot-publishing-pipeline",
+  "content_markdown": "# Designing an SSOT Publishing Pipeline\n\n…",
+  "tags": ["python", "automation", "seo"],
+  "platforms": {
+    "substack": { "tables": "error" },
+    "medium":   { "publish_as_draft": true },
+    "dev_to":   { "publish_as_draft": true },
+    "hashnode": { "publish_as_draft": true }
+  }
+}
+```
+
+## Configuration
+
+Secrets and settings load from `.env` (see
+[`.env.example`](.env.example)) — copy it and fill in what you use:
+
+```bash
+cp .env.example .env
+```
+
+Every platform is optional; omit a platform's secrets (or its `platforms`
+entry) to skip it.
+
+## Using it from Python
+
+The CLI is a thin wrapper over the same functions, so everything is callable
+programmatically:
+
+```python
+import asyncio
+from article import load_article, publish_primary, syndicate_secondary
+
+art = load_article("article.json")
+asyncio.run(publish_primary(art))  # phase 1 → records canonical_url
+asyncio.run(syndicate_secondary(art))  # phase 2 → canonical SEO everywhere
+```
+
+## Adding a platform
+
+Adapters are registered in an open-closed registry. To add a platform, write
+one async function satisfying the `PublishAdapter` protocol and register it —
+no core changes:
+
+```python
+from article import register_adapter, PublishResult
+from article.util import require_canonical_url
+
+
+@register_adapter("my_platform")
+async def publish(article, *, canonical_url, config, secrets):
+    require_canonical_url("my_platform", canonical_url)  # SSOT is never optional
+    # … call the platform's API, injecting canonical_url …
+    return PublishResult.success("my_platform", url="…", canonical_url=canonical_url)
+```
+
+## Architecture
+
+| Layer | Module | Responsibility |
+|------|--------|----------------|
+| Schema + config | `article/config.py` | Pydantic `Article` model, `.env` `Settings`, `load_article` (friendly errors) |
+| Vocabulary | `article/base.py` | `PublishResult`, `RunSummary`, platform names, exceptions |
+| State store | `article/state.py` | `MutableMapping` facade over JSON, keyed by slug (the SSOT) |
+| Registry | `article/registry.py` | `PublishAdapter` protocol + open-closed registry |
+| Engine | `article/engine.py` | Orchestrates phase 1 → phase 2; canonical handoff; graceful errors |
+| Adapters | `article/adapters/*` | One module per platform (config + secrets injected) |
+| CLI | `article/__main__.py` | `cw` dispatch of the two commands |
+
+> **Status, per platform:**
+>
+> - **Substack**: real. Creates unpublished drafts through python-substack; never publishes.
+> - **Medium**: honest manual step. Its API is closed to new integrations, so the adapter sends nothing and reports a `[todo]` result: open Medium's *Import a story* page (https://medium.com/p/import) and paste the published Substack URL, which sets the canonical link.
+> - **Dev.to, Hashnode**: still stubs; they build the payload (with the canonical field) but make no network call.

{article-0.1.3 → article-0.1.5}/article/__init__.py

@@ -45,6 +45,7 @@ from .base import (
     ArticleError,
     ArticleValidationError,
     CanonicalUrlMissing,
+    CanonicalUrlNotLive,
     ConfigError,
     Phase,
     PlatformName,
@@ -122,6 +123,7 @@ __all__ = [
     "AdapterError",
     "UnknownPlatformError",
     "CanonicalUrlMissing",
+    "CanonicalUrlNotLive",
     # state
     "JsonStateStore",
     "default_state_store",

article-0.1.5/article/__main__.py

@@ -0,0 +1,220 @@
+# PYTHON_ARGCOMPLETE_OK
+"""Command-line entry point for the ``article`` publishing pipeline.
+
+Two commands mirror the two phases, and a third is the everyday shortcut for
+phase 1 — all thin wrappers over the very same :mod:`article.engine` and
+adapter functions the Python API exposes (dispatch-to-interface: one
+implementation, many front-ends)::
+
+    python -m article publish-primary      article.json
+    python -m article syndicate-secondary  article.json
+    python -m article draft-substack       essay.md      # unpublished draft
+    python -m article draft-substack       essay.md --dry-run   # no credentials
+
+Common options: ``--env-file`` (where to read secrets), ``--state-path``
+(the SSOT state file), ``--json-out`` (machine-readable summary). Phase 2 also
+takes ``--platforms medium,dev_to`` to syndicate a subset.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Optional
+
+import cw
+
+from .adapters import substack as _substack
+from .base import SUBSTACK, ArticleError, RunSummary
+from .config import SubstackConfig, load_article, load_settings
+from .engine import publish_primary as _publish_primary
+from .engine import syndicate_secondary as _syndicate_secondary
+from .state import JsonStateStore
+from .util import run_sync
+
+
+def _render(summary: RunSummary, *, json_out: bool) -> str:
+    return json.dumps(summary.as_record(), indent=2) if json_out else summary.render()
+
+
+def _prepare(article_path: str, *, env_file: Optional[str], state_path: Optional[str]):
+    """Shared setup: load settings + article + state store (with friendly errors)."""
+    try:
+        overrides = {"state_path": state_path} if state_path else {}
+        settings = load_settings(env_file=env_file, **overrides)
+        article = load_article(article_path)
+    except ArticleError as e:
+        raise cw.CommandError(str(e)) from e
+    store = JsonStateStore(settings.state_path)
+    return settings, article, store
+
+
+def publish_primary(
+    article_path: str,
+    *,
+    env_file: Optional[str] = None,
+    state_path: Optional[str] = None,
+    json_out: bool = False,
+):
+    """Phase 1 — publish to the primary platform (Substack) and record canonical_url."""
+    settings, article, store = _prepare(
+        article_path, env_file=env_file, state_path=state_path
+    )
+    summary = run_sync(_publish_primary(article, settings=settings, store=store))
+    return _render(summary, json_out=json_out)
+
+
+def syndicate_secondary(
+    article_path: str,
+    *,
+    env_file: Optional[str] = None,
+    state_path: Optional[str] = None,
+    platforms: Optional[str] = None,
+    allow_unpublished: bool = False,
+    json_out: bool = False,
+):
+    """Phase 2 — syndicate to secondary platforms, injecting canonical_url for SEO.
+
+    Refused while the Substack post is still a draft (its URL would be a 404), unless
+    ``allow_unpublished``.
+    """
+    settings, article, store = _prepare(
+        article_path, env_file=env_file, state_path=state_path
+    )
+    selected = [p.strip() for p in platforms.split(",")] if platforms else None
+    try:
+        summary = run_sync(
+            _syndicate_secondary(
+                article,
+                settings=settings,
+                store=store,
+                platforms=selected,
+                allow_unpublished=allow_unpublished,
+            )
+        )
+    except ArticleError as e:
+        raise cw.CommandError(str(e)) from e
+    return _render(summary, json_out=json_out)
+
+
+def _render_dry_run(report: dict) -> str:
+    counts = ", ".join(f"{n} {k}" for k, n in report["counts"].items()) or "empty"
+    lines = [
+        f"Dry run (nothing sent): {report['title']!r} -> slug {report['slug']}",
+        f"  converts to: {counts}",
+        *(f"  warning: {w}" for w in report["warnings"]),
+    ]
+    return "\n".join(lines)
+
+
+def draft_substack(
+    article_path: str,
+    *,
+    env_file: Optional[str] = None,
+    state_path: Optional[str] = None,
+    tables: Optional[str] = None,
+    dry_run: bool = False,
+    update: bool = False,
+    overwrite_edits: bool = False,
+    json_out: bool = False,
+):
+    """Create an UNPUBLISHED Substack draft from a Markdown file; never publishes.
+
+    With ``update``, rewrite the draft this article's earlier run created (from the
+    state file) instead of creating another one.
+    """
+    settings, article, store = _prepare(
+        article_path, env_file=env_file, state_path=state_path
+    )
+    config = article.platforms.substack or SubstackConfig()
+    if tables is not None:
+        config = config.model_copy(update={"tables": tables})
+    earlier = store.get(article.slug, {}).get("primary", {}).get("detail", {})
+    if update:
+        if not earlier.get("draft_id"):
+            raise cw.CommandError(
+                f"--update: no earlier draft is recorded for {article.slug!r} in the "
+                f"state file; run once without --update first"
+            )
+        config = config.model_copy(
+            update={
+                "draft_id": earlier["draft_id"],
+                "expected_revision": earlier.get("revision"),
+                "overwrite_edits": overwrite_edits,
+            }
+        )
+    try:
+        if dry_run:
+            report = _substack.dry_run(article, config=config)
+            return json.dumps(report, indent=2) if json_out else _render_dry_run(report)
+        platforms = article.platforms.model_copy(update={SUBSTACK: config})
+        article = article.model_copy(update={"platforms": platforms})
+        summary = run_sync(_publish_primary(article, settings=settings, store=store))
+    except ArticleError as e:
+        raise cw.CommandError(str(e)) from e
+    if not summary.ok:
+        raise cw.CommandError(summary.failures[0].error)
+    if json_out:
+        return _render(summary, json_out=True)
+    detail = summary.by_platform[SUBSTACK].detail
+    lines = [summary.render(), f"Edit the draft: {detail.get('edit_url')}"]
+    lines += [f"  warning: {w}" for w in detail.get("warnings", ())]
+    if earlier.get("edit_url") and not update:
+        lines.append(
+            f"Note: an earlier draft of this article is still on Substack "
+            f"({earlier['edit_url']}); delete it if this one replaces it."
+        )
+    return "\n".join(lines)
+
+
+#: SSOT list of dispatchable commands (``cw`` maps ``_`` in names to ``-``).
+_dispatch_funcs = [publish_primary, syndicate_secondary, draft_substack]
+
+#: Per-parameter ``add_argument`` particulars the signature cannot carry -- here, the
+#: one ``help`` string that used to ride on an ``@argh.arg`` decorator. ``cw`` reads
+#: ``config``, never decorator metadata, so this is where such declarations live now.
+_dispatch_config = {
+    command: {"article_path": {"help": "Path to the article JSON file"}}
+    for command in ("publish-primary", "syndicate-secondary")
+}
+_dispatch_config["syndicate-secondary"]["allow_unpublished"] = {
+    "help": "Syndicate even though the Substack post is still a draft (its URL is a 404)"
+}
+_dispatch_config["draft-substack"] = {
+    "article_path": {"help": "Path to the essay Markdown file (or article JSON)"},
+    "tables": {
+        "choices": ["error", "code", "image"],
+        "help": "Markdown tables: refuse (error, the default), keep as code blocks, "
+        "or render to an image (needs article[images])",
+    },
+    "update": {
+        "help": "Rewrite the draft an earlier run created instead of making a new one"
+    },
+    "overwrite_edits": {
+        "help": "With --update: replace edits made in the Substack editor since the last run"
+    },
+    "dry_run": {"help": "Check and convert only; no credentials, nothing sent"},
+}
+
+
+def mk_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser -- a plain :class:`argparse.ArgumentParser`, no I/O.
+
+    The single place the command list and its per-parameter declarations meet, so a
+    test that inspects the grammar inspects the very parser :func:`main` dispatches.
+    """
+    return cw.mk_parser(_dispatch_funcs, config=_dispatch_config)
+
+
+def main() -> int:
+    """Dispatch a CLI command and return its exit code.
+
+    ``cw.run`` offers the parser to ``argcomplete`` itself (the
+    ``# PYTHON_ARGCOMPLETE_OK`` marker on line 1 is what the shell hook looks for),
+    so there is no hand-written completion block to keep in step.
+    """
+    return cw.run(mk_parser())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

article-0.1.5/article/adapters/medium.py

@@ -0,0 +1,66 @@
+"""Medium adapter — Phase 2, as an honest manual step ("Import a story").
+
+Medium's REST API is closed to new integrations (no new integration tokens
+are issued, and the API docs repository is archived), so this adapter does
+**not** post anything. Medium's own *Import a story* tool is the supported
+route, and it sets the imported story's canonical link to the original URL,
+which is exactly the SEO handoff this pipeline exists for.
+
+The adapter returns a :meth:`~article.base.PublishResult.manual` result whose
+``next_step`` names the URL to import and where to paste it. Nothing is ever
+published to Medium.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from ..base import MEDIUM, PublishResult
+from ..config import Article, MediumConfig
+from ..registry import register_adapter
+from ..util import require_canonical_url
+
+#: Medium's "Import a story" page (Profile menu > Stories > Import a story).
+MEDIUM_IMPORT_URL = "https://medium.com/p/import"
+
+
+def import_steps(canonical_url: str) -> str:
+    """The one-line instruction for importing ``canonical_url`` into Medium.
+
+    >>> import_steps("https://me.substack.com/p/t")  # doctest: +ELLIPSIS
+    'Once https://me.substack.com/p/t is live, open https://medium.com/p/import, ...'
+    """
+    return (
+        f"Once {canonical_url} is live, open {MEDIUM_IMPORT_URL}, paste that URL "
+        f"and press Import; Medium sets the canonical link to it. Review the "
+        f"imported draft (footnotes, tables, captions) before publishing."
+    )
+
+
+@register_adapter(MEDIUM)
+async def publish(
+    article: Article,
+    *,
+    canonical_url: Optional[str],
+    config: MediumConfig,
+    secrets: Mapping[str, Any],
+) -> PublishResult:
+    """Return the *Import a story* step for ``article``; sends nothing to Medium.
+
+    >>> import asyncio
+    >>> from article.config import Article, MediumConfig
+    >>> art = Article(title="T", slug="t", content_markdown="x")
+    >>> res = asyncio.run(publish(
+    ...     art, canonical_url="https://me.substack.com/p/t",
+    ...     config=MediumConfig(), secrets={},
+    ... ))
+    >>> res.state.value, res.detail["import_url"]
+    ('manual', 'https://me.substack.com/p/t')
+    """
+    require_canonical_url(MEDIUM, canonical_url)
+    return PublishResult.manual(
+        MEDIUM,
+        next_step=import_steps(canonical_url),
+        canonical_url=canonical_url,
+        detail={"import_url": canonical_url, "import_page": MEDIUM_IMPORT_URL},
+    )