blog-cli 0.1.0__py3-none-any.whl

blog_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: blog-cli
+Version: 0.1.0
+Summary: Agent-friendly CLI for managing a blog. Create drafts, upload media, generate time-limited preview links.
+Author: tanaka-mambinge
+License: MIT
+Project-URL: Repository, https://github.com/tanaka-mambinge/personal
+Project-URL: Issues, https://github.com/tanaka-mambinge/personal/issues
+Keywords: blog,cli,agent,markdown,writing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+Requires-Dist: typer>=0.16
+Provides-Extra: dev
+Requires-Dist: asgi-lifespan>=2.1; extra == "dev"
+Requires-Dist: fastapi>=0.115; extra == "dev"
+Requires-Dist: motor>=3.7; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pydantic>=2.10; extra == "dev"
+Requires-Dist: pydantic-settings>=2.6; extra == "dev"
+Requires-Dist: pymongo>=4.9; extra == "dev"
+Requires-Dist: python-multipart>=0.0.20; extra == "dev"
+Requires-Dist: uvicorn>=0.49; extra == "dev"
+
+# blog-cli
+
+Agent-friendly CLI for managing a personal blog. Create drafts, upload media, generate time-limited preview links — all from the command line.
+
+Designed for use by both humans and AI agents.
+
+## Install
+
+```bash
+pipx install blog-cli
+# or
+uv tool install blog-cli
+```
+
+For development:
+
+```bash
+git clone https://github.com/tanaka-mambinge/personal
+cd personal/blog-cli
+uv sync --extra dev
+```
+
+## Configure
+
+Set these env vars (e.g. in `~/.zshrc`):
+
+```bash
+export PERSONAL_SERVER_URL="https://api.personal.localhost:1355"
+export PERSONAL_API_KEY="your-api-key"
+export PERSONAL_SITE_URL="https://personal.localhost:1355"
+```
+
+Empty `PERSONAL_API_KEY` disables auth if your server has no key configured.
+
+## Usage
+
+### Articles
+
+```bash
+# Create a draft
+blog-cli article create \
+  --title "My Post" \
+  --description "A short summary" \
+  --type blog \
+  --markdown "# My Post\n\nHello."
+
+# List published blog posts
+blog-cli article list --type blog
+
+# Show an article
+blog-cli article show my-post
+
+# Update an article
+blog-cli article update my-post --title "Better Title"
+
+# Generate a 24h preview link for a draft
+blog-cli article preview my-post
+
+# Custom TTL (1–168 hours)
+blog-cli article preview my-post --ttl-hours 4
+
+# Publish
+blog-cli article publish my-post --published-by agent
+
+# Delete (soft)
+blog-cli article delete my-post
+
+# Unarchive (restore deleted)
+blog-cli article unarchive my-post
+```
+
+All commands support `--json` for machine-readable output and `--server-url` to override the server.
+
+### Media
+
+```bash
+# Upload (name is the unique key used in markdown)
+blog-cli media upload --name hero-image ./hero.jpg
+
+# Update (replace the file, keep the name)
+blog-cli media update --name hero-image ./new-hero.jpg
+
+# Delete (soft)
+blog-cli media delete --name hero-image
+```
+
+### Markdown Image References
+
+Upload media with a name, then reference it in article markdown:
+
+```markdown
+![Hero image](hero-image)
+
+<video controls width="100%" src="ambulance-video"></video>
+```
+
+The site resolves these to full URLs automatically.
+
+## Testing
+
+```bash
+uv run pytest -v
+```
+
+Spins up a temp MongoDB + server via test fixtures. No external deps needed.
+
+## Architecture
+
+```
+CLI (httpx) → FastAPI server → Motor/GridFS → MongoDB
+```
+
+- **Public endpoints** (GET) — list and read published articles, download media
+- **Protected endpoints** (POST/PATCH/PUT/DELETE) — require `Authorization: Bearer <key>`
+
+## License
+
+MIT

blog_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+personal_cli/__init__.py,sha256=zSLVFHJp7dRslRHiL0NBg999NSi0kBHsSDCe4Pko_TM,29
+personal_cli/__main__.py,sha256=Q-h9Re4o1TQV5QtcL-r7JCJvuoU9rvdJs9HMqsdiZ6E,75
+personal_cli/cli.py,sha256=QKGvWM0fzPH0ySIR3UZ5w19KWMMv85Eu_0HmF0D013M,9793
+personal_cli/client.py,sha256=XKj_cuel7eXxkmiddU-GUkvkCq5ttY-DC2KJL89gynw,5410
+personal_cli/formatting.py,sha256=6ExLa1unUKp0DM3WGj7Z3_OO1XAoo3eUMHOo2jDwM6o,972
+blog_cli-0.1.0.dist-info/METADATA,sha256=ZN9VWYphkZJVAxtKH-GqFlJCaZjhNu8giGvDfiFdN38,3656
+blog_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+blog_cli-0.1.0.dist-info/entry_points.txt,sha256=bwoGco668a8rk3HGGzzHAOeTa27RP1QPo_arD9pbbIA,51
+blog_cli-0.1.0.dist-info/top_level.txt,sha256=3y2DqdgZGcLQJNm0sO-0kIWFLtAYP90FPffxql9gGGM,13
+blog_cli-0.1.0.dist-info/RECORD,,

blog_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

blog_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+blog-cli = personal_cli.cli:main

blog_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+personal_cli

personal_cli/__init__.py

@@ -0,0 +1,2 @@
+"""Personal article CLI."""
+

personal_cli/__main__.py

@@ -0,0 +1,6 @@
+from personal_cli.cli import main
+
+
+if __name__ == "__main__":
+    main()
+

personal_cli/cli.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import typer
+
+from personal_cli.client import ArticleApiClient, CLIError, get_default_config
+from personal_cli.formatting import emit_result, read_markdown_from_source
+
+app = typer.Typer(help="Agent-facing article CLI.")
+article_app = typer.Typer(help="Manage articles.")
+media_app = typer.Typer(help="Manage media uploads.")
+
+app.add_typer(article_app, name="article")
+app.add_typer(media_app, name="media")
+
+
+def build_client(server_url: str | None = None) -> ArticleApiClient:
+    url, api_key = get_default_config()
+    return ArticleApiClient(server_url or url, api_key=api_key)
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+@article_app.command("list")
+def article_list(
+    type_filter: str = typer.Option("all", "--type", help="all, blog, or project."),
+    status: str | None = typer.Option(None, "--status", help="Filter by article status."),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        client = build_client(server_url)
+        articles = run(client.list_articles(status=status, type_filter=type_filter))
+        emit_result(articles, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@article_app.command("show")
+def article_show(
+    slug: str,
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        client = build_client(server_url)
+        article = run(client.get_article(slug))
+        emit_result(article, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@article_app.command("create")
+def article_create(
+    title: str = typer.Option(..., "--title", help="Article title."),
+    description: str = typer.Option(..., "--description", help="Short summary."),
+    slug: str | None = typer.Option(None, "--slug", help="Optional slug override."),
+    tag: list[str] = typer.Option([], "--tag", help="Repeat for each tag."),
+    article_type: str = typer.Option(..., "--type", help="blog or project."),
+    status: str = typer.Option("draft", "--status", help="draft or published."),
+    markdown: str | None = typer.Option(None, "--markdown", help="Inline markdown body."),
+    markdown_file: Path | None = typer.Option(None, "--markdown-file", exists=True, readable=True, dir_okay=False),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        body = read_markdown_from_source(markdown=markdown, markdown_file=markdown_file)
+        client = build_client(server_url)
+        payload = {
+            "title": title,
+            "description": description,
+            "slug": slug,
+            "tags": tag,
+            "type": article_type,
+            "status": status,
+            "markdown": body,
+        }
+        article = run(client.create_article(payload))
+        emit_result(article, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@article_app.command("update")
+def article_update(
+    slug: str,
+    title: str | None = typer.Option(None, "--title", help="New title."),
+    description: str | None = typer.Option(None, "--description", help="New summary."),
+    tag: list[str] | None = typer.Option(None, "--tag", help="Repeat for each tag."),
+    article_type: str | None = typer.Option(None, "--type", help="blog or project."),
+    status: str | None = typer.Option(None, "--status", help="draft or published."),
+    markdown: str | None = typer.Option(None, "--markdown", help="Inline markdown body."),
+    markdown_file: Path | None = typer.Option(None, "--markdown-file", exists=True, readable=True, dir_okay=False),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        client = build_client(server_url)
+        payload: dict[str, object] = {}
+        if title is not None:
+            payload["title"] = title
+        if description is not None:
+            payload["description"] = description
+        if tag is not None:
+            payload["tags"] = tag
+        if article_type is not None:
+            payload["type"] = article_type
+        if status is not None:
+            payload["status"] = status
+        if markdown is not None or markdown_file is not None:
+            payload["markdown"] = read_markdown_from_source(markdown=markdown, markdown_file=markdown_file)
+        article = run(client.update_article(slug, payload))
+        emit_result(article, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@article_app.command("publish")
+def article_publish(
+    slug: str,
+    published_by: str | None = typer.Option(None, "--published-by", help="Who published the article."),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        client = build_client(server_url)
+        article = run(client.publish_article(slug, {"published_by": published_by} if published_by else None))
+        emit_result(article, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@article_app.command("delete")
+def article_delete(
+    slug: str,
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        client = build_client(server_url)
+        result = run(client.delete_article(slug))
+        emit_result(result, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@article_app.command("unarchive")
+def article_unarchive(
+    slug: str,
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        client = build_client(server_url)
+        article = run(client.unarchive_article(slug))
+        emit_result(article, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@article_app.command("preview")
+def article_preview(
+    slug: str,
+    ttl_hours: int = typer.Option(24, "--ttl-hours", help="Hours until the preview link expires."),
+    site_url: str | None = typer.Option(None, "--site-url", help="Base URL of the personal site."),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        import os
+        resolved_site_url = site_url or os.environ.get("PERSONAL_SITE_URL", "http://localhost:3000")
+        client = build_client(server_url)
+        result = run(client.generate_preview(slug, ttl_hours=ttl_hours, base_url=resolved_site_url))
+        emit_result(result, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@media_app.command("upload")
+def media_upload(
+    name: str = typer.Option(..., "--name", help="Unique name for the media (e.g. hero-image)."),
+    path: Path = typer.Argument(..., exists=True, file_okay=True, dir_okay=False, readable=True),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        client = build_client(server_url)
+        result = run(client.upload_media(name, path))
+        emit_result(result, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@media_app.command("update")
+def media_update(
+    name: str = typer.Option(..., "--name", help="Name of the media to replace."),
+    path: Path = typer.Argument(..., exists=True, file_okay=True, dir_okay=False, readable=True),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        client = build_client(server_url)
+        result = run(client.update_media(name, path))
+        emit_result(result, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@media_app.command("delete")
+def media_delete(
+    name: str = typer.Option(..., "--name", help="Name of the media to delete."),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON output."),
+    server_url: str | None = typer.Option(None, "--server-url", help="FastAPI base URL."),
+) -> None:
+    try:
+        client = build_client(server_url)
+        result = run(client.delete_media(name))
+        emit_result(result, json_output=json_output)
+    except CLIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

personal_cli/client.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+class CLIError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ArticleApiClient:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.transport = transport
+        self.timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        if not self.api_key:
+            return {}
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    async def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | list[Any] | None = None,
+        params: dict[str, Any] | None = None,
+        files: Any = None,
+    ) -> Any:
+        async with httpx.AsyncClient(
+            base_url=self.base_url,
+            transport=self.transport,
+            timeout=self.timeout,
+            headers=self._headers(),
+        ) as client:
+            response = await client.request(method, path, json=json, params=params, files=files)
+            if response.status_code >= 400:
+                message = response.text.strip() or response.reason_phrase
+                raise CLIError(f"{method} {path} failed: {response.status_code} {message}", status_code=response.status_code)
+            if response.content:
+                return response.json()
+            return None
+
+    async def list_articles(self, *, status: str | None = None, type_filter: str = "all") -> list[dict[str, Any]]:
+        params: dict[str, Any] = {"type": type_filter}
+        if status is not None:
+            params["status_filter"] = status
+        result = await self._request_json("GET", "/api/v1/articles", params=params)
+        return list(result or [])
+
+    async def get_article(self, slug: str) -> dict[str, Any]:
+        result = await self._request_json("GET", f"/api/v1/articles/{slug}")
+        return dict(result)
+
+    async def create_article(self, payload: dict[str, Any]) -> dict[str, Any]:
+        result = await self._request_json("POST", "/api/v1/articles", json=payload)
+        return dict(result)
+
+    async def update_article(self, slug: str, payload: dict[str, Any]) -> dict[str, Any]:
+        result = await self._request_json("PATCH", f"/api/v1/articles/{slug}", json=payload)
+        return dict(result)
+
+    async def publish_article(self, slug: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        result = await self._request_json("POST", f"/api/v1/articles/{slug}/publish", json=payload)
+        return dict(result)
+
+    async def unarchive_article(self, slug: str) -> dict[str, Any]:
+        result = await self._request_json("POST", f"/api/v1/articles/{slug}/unarchive")
+        return dict(result)
+
+    async def delete_article(self, slug: str) -> dict[str, Any]:
+        result = await self._request_json("DELETE", f"/api/v1/articles/{slug}")
+        return dict(result or {})
+
+    async def upload_media(self, name: str, path: Path) -> dict[str, Any]:
+        with path.open("rb") as handle:
+            result = await self._request_json(
+                "POST",
+                "/api/v1/media",
+                params={"name": name},
+                files={"file": (path.name, handle, "application/octet-stream")},
+            )
+        return dict(result)
+
+    async def update_media(self, name: str, path: Path) -> dict[str, Any]:
+        with path.open("rb") as handle:
+            result = await self._request_json(
+                "PUT",
+                f"/api/v1/media/{name}",
+                files={"file": (path.name, handle, "application/octet-stream")},
+            )
+        return dict(result)
+
+    async def delete_media(self, name: str) -> dict[str, Any]:
+        result = await self._request_json("DELETE", f"/api/v1/media/{name}")
+        return dict(result or {})
+
+    async def generate_preview(self, slug: str, *, ttl_hours: int = 24, base_url: str = "http://localhost:3000") -> dict[str, Any]:
+        result = await self._request_json(
+            "POST",
+            f"/api/v1/articles/{slug}/preview",
+            params={"ttl_hours": ttl_hours, "base_url": base_url},
+        )
+        return dict(result)
+
+
+def get_default_config() -> tuple[str, str | None]:
+    import os
+    _load_dotenv()
+    return (
+        os.environ.get("PERSONAL_SERVER_URL", "http://127.0.0.1:8000"),
+        os.environ.get("PERSONAL_API_KEY"),
+    )
+
+
+def _load_dotenv() -> None:
+    import os
+    from pathlib import Path
+
+    candidates = [
+        Path.cwd() / ".env",
+        Path(__file__).resolve().parents[3] / ".env",
+    ]
+    for env_path in candidates:
+        if not env_path.exists():
+            continue
+        with env_path.open() as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if "=" not in line:
+                    continue
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip().strip("'\"")
+                os.environ[key] = value
+        break

personal_cli/formatting.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from personal_cli.client import CLIError
+
+
+def read_markdown_from_source(
+    *,
+    markdown: str | None,
+    markdown_file: Path | None,
+) -> str:
+    if markdown is not None and markdown_file is not None:
+        raise CLIError("Use either --markdown or --markdown-file, not both.")
+    if markdown is not None:
+        return markdown
+    if markdown_file is not None:
+        return markdown_file.read_text(encoding="utf-8")
+    if sys.stdin.isatty():
+        raise CLIError("Provide markdown via --markdown, --markdown-file, or stdin.")
+    return sys.stdin.read()
+
+
+def emit_result(data: Any, *, json_output: bool = False) -> None:
+    if json_output:
+        print(json.dumps(data, indent=2, ensure_ascii=False, default=str))
+        return
+
+    if isinstance(data, list):
+        for item in data:
+            print(item)
+        return
+
+    print(data)
+