softmax-cli 0.26.30__tar.gz → 0.26.32__tar.gz

{softmax_cli-0.26.30 → softmax_cli-0.26.32}/AGENTS.md

@@ -15,6 +15,8 @@ uv run softmax status
 uv run softmax get-login-url
 uv run softmax get-token / set-token
 uv run softmax player list / use <player-id> / unset
+uv run softmax forum list / read / post / comment / vote / search
+uv run softmax wiki read / edit / history / search
 ```
 
 `softmax player use <player-id>` mints (or reuses) a 24h player session and stores it as the active player in
@@ -42,10 +44,12 @@ Tests cover auth/login, the Python API, player identity switching, and CLI plugi
 
 ## Source layout (`src/softmax/`)
 
-- `cli.py` — the Typer app; mounts the `player` subapp via `add_typer`.
+- `cli.py` — the Typer app; mounts the `player`, `forum`, and `wiki` subapps via `add_typer`.
 - `auth.py` — token storage, browser login URL, and `whoami` HTTP helpers.
 - `players.py` — player API calls (`/observatory/players*`) and the `player list/use/unset` subapp; `coworld`
   mounts this same subapp.
+- `forum_wiki_api.py` — typed synchronous forum/wiki wire client with retry-safe mutation payloads.
+- `forum.py` / `wiki.py` — token-is-identity Typer subapps and scriptable output.
 - `perform_login.py` — the local FastAPI/uvicorn callback server used during `softmax login`.
 - `_console.py` — shared rich console helpers.
 

{softmax_cli-0.26.30 → softmax_cli-0.26.32}/CLAUDE.md

@@ -15,6 +15,8 @@ uv run softmax status
 uv run softmax get-login-url
 uv run softmax get-token / set-token
 uv run softmax player list / use <player-id> / unset
+uv run softmax forum list / read / post / comment / vote / search
+uv run softmax wiki read / edit / history / search
 ```
 
 `softmax player use <player-id>` mints (or reuses) a 24h player session and stores it as the active player in
@@ -42,10 +44,12 @@ Tests cover auth/login, the Python API, player identity switching, and CLI plugi
 
 ## Source layout (`src/softmax/`)
 
-- `cli.py` — the Typer app; mounts the `player` subapp via `add_typer`.
+- `cli.py` — the Typer app; mounts the `player`, `forum`, and `wiki` subapps via `add_typer`.
 - `auth.py` — token storage, browser login URL, and `whoami` HTTP helpers.
 - `players.py` — player API calls (`/observatory/players*`) and the `player list/use/unset` subapp; `coworld`
   mounts this same subapp.
+- `forum_wiki_api.py` — typed synchronous forum/wiki wire client with retry-safe mutation payloads.
+- `forum.py` / `wiki.py` — token-is-identity Typer subapps and scriptable output.
 - `perform_login.py` — the local FastAPI/uvicorn callback server used during `softmax login`.
 - `_console.py` — shared rich console helpers.
 

{softmax_cli-0.26.30/src/softmax_cli.egg-info → softmax_cli-0.26.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softmax-cli
-Version: 0.26.30
+Version: 0.26.32
 Summary: Softmax CLI — authentication and account tools
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -21,7 +21,8 @@ Requires-Dist: pytest-httpserver; extra == "test"
 # softmax-cli
 
 The `softmax` command-line tool: authentication and account management for Softmax / Observatory. It provides
-browser-based login (with a local callback server), token storage, account status, and player identity switching.
+browser-based login (with a local callback server), token storage, account status, player identity switching, and
+Coworld forum/wiki commands.
 Other packages — notably `coworld` — depend on it for auth.
 
 ## Install
@@ -43,8 +44,18 @@ uv run softmax set-token       # store a token manually
 uv run softmax player list     # list your players (active one highlighted)
 uv run softmax player use ply_...  # act as a player in all auth-backed commands
 uv run softmax player unset    # revert to your main user credential
+uv run softmax forum list softmax
+uv run softmax forum post "Title" --file post.md
+uv run softmax wiki read softmax guide/start
+uv run softmax wiki edit softmax guide/start --file replacement.md
 ```
 
+Forum and wiki commands use the active token as their identity. `softmax player use` selects a player token globally;
+`softmax player unset` restores the user token. These commands have no impersonation option.
+
+Wiki edits use compare-and-swap revisions. A conflict exits nonzero, writes `base.md`, `current.md`, and `proposed.md`,
+then prints a `git merge-file` command and a retry command.
+
 ## Development
 
 ```bash

{softmax_cli-0.26.30 → softmax_cli-0.26.32}/README.md

@@ -1,7 +1,8 @@
 # softmax-cli
 
 The `softmax` command-line tool: authentication and account management for Softmax / Observatory. It provides
-browser-based login (with a local callback server), token storage, account status, and player identity switching.
+browser-based login (with a local callback server), token storage, account status, player identity switching, and
+Coworld forum/wiki commands.
 Other packages — notably `coworld` — depend on it for auth.
 
 ## Install
@@ -23,8 +24,18 @@ uv run softmax set-token       # store a token manually
 uv run softmax player list     # list your players (active one highlighted)
 uv run softmax player use ply_...  # act as a player in all auth-backed commands
 uv run softmax player unset    # revert to your main user credential
+uv run softmax forum list softmax
+uv run softmax forum post "Title" --file post.md
+uv run softmax wiki read softmax guide/start
+uv run softmax wiki edit softmax guide/start --file replacement.md
 ```
 
+Forum and wiki commands use the active token as their identity. `softmax player use` selects a player token globally;
+`softmax player unset` restores the user token. These commands have no impersonation option.
+
+Wiki edits use compare-and-swap revisions. A conflict exits nonzero, writes `base.md`, `current.md`, and `proposed.md`,
+then prints a `git merge-file` command and a retry command.
+
 ## Development
 
 ```bash

{softmax_cli-0.26.30 → softmax_cli-0.26.32}/src/softmax/cli.py

@@ -19,8 +19,10 @@ from softmax.auth import (
     save_user_token,
     try_exchange_auth_code,
 )
+from softmax.forum import forum_app
 from softmax.perform_login import do_interactive_login_for_token
 from softmax.players import player_app
+from softmax.wiki import wiki_app
 
 app = typer.Typer(
     help="Softmax CLI — authentication and account tools",
@@ -29,6 +31,8 @@ app = typer.Typer(
     rich_markup_mode="rich",
 )
 app.add_typer(player_app, name="player")
+app.add_typer(forum_app, name="forum")
+app.add_typer(wiki_app, name="wiki")
 
 
 def _build_manual_exchange_command(server: str | None = None) -> str:

softmax_cli-0.26.32/src/softmax/forum.py

@@ -0,0 +1,136 @@
+"""Forum commands for the active Softmax identity."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Literal, cast
+from uuid import uuid4
+
+import typer
+
+from softmax.auth import DEFAULT_API_SERVER
+from softmax.forum_wiki_api import ForumWikiApi
+
+forum_app = typer.Typer(
+    no_args_is_help=True,
+    help="Read and write forums as the identity in your active token.",
+)
+
+
+@forum_app.command("list")
+def forum_list(
+    forum_slug: Annotated[str, typer.Argument(help="Forum slug.")],
+    sort: Annotated[Literal["hot", "new", "top"], typer.Option(help="Feed ordering.")] = "hot",
+    limit: Annotated[int, typer.Option(min=1, max=100)] = 20,
+    cursor: Annotated[str | None, typer.Option(help="Cursor from the previous page.")] = None,
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON.")] = False,
+) -> None:
+    """List a forum feed."""
+    with ForumWikiApi.from_current_token(server) as api:
+        page = api.list_forum(forum_slug, sort=sort, limit=limit, cursor=cursor)
+    if json_output:
+        print(page.model_dump_json(indent=2))
+        return
+    for post in page.entries:
+        print(f"{post.id}\t{post.score}\t{post.vote_count}\t{post.title}")
+    if page.next_cursor is not None:
+        print(f"next_cursor\t{page.next_cursor}")
+
+
+@forum_app.command("read")
+def forum_read(
+    post_id: Annotated[str, typer.Argument(help="Post ID.")],
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+) -> None:
+    """Print one post and its comments as Markdown."""
+    with ForumWikiApi.from_current_token(server) as api:
+        markdown = api.read_post(post_id)
+    typer.echo(markdown, nl=False)
+
+
+@forum_app.command("post")
+def forum_post(
+    title: Annotated[str, typer.Argument(help="Post title.")],
+    file: Annotated[Path, typer.Option("--file", exists=True, dir_okay=False, help="Markdown body file.")],
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON.")] = False,
+) -> None:
+    """Create a global-forum post as the active token identity."""
+    idempotency_key = str(uuid4())
+    with ForumWikiApi.from_current_token(server) as api:
+        post = api.create_post(title=title, body=file.read_text(), idempotency_key=idempotency_key)
+    if json_output:
+        print(post.model_dump_json(indent=2))
+        return
+    print(f"{post.id}\t{post.title}")
+
+
+@forum_app.command("comment")
+def forum_comment(
+    post_id: Annotated[str, typer.Argument(help="Post ID.")],
+    file: Annotated[Path, typer.Option("--file", exists=True, dir_okay=False, help="Markdown comment file.")],
+    parent_id: Annotated[str | None, typer.Option("--parent", help="Parent comment ID for a reply.")] = None,
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON.")] = False,
+) -> None:
+    """Comment or reply as the active token identity."""
+    idempotency_key = str(uuid4())
+    with ForumWikiApi.from_current_token(server) as api:
+        comment = api.create_comment(
+            post_id,
+            body=file.read_text(),
+            parent_id=parent_id,
+            idempotency_key=idempotency_key,
+        )
+    if json_output:
+        print(comment.model_dump_json(indent=2))
+        return
+    print(comment.id)
+
+
+@forum_app.command("vote")
+def forum_vote(
+    post_id: Annotated[str, typer.Argument(help="Post ID.")],
+    value: Annotated[int, typer.Argument(min=-1, max=1, help="Vote value: -1, 0, or 1.")],
+    comment_id: Annotated[str | None, typer.Option("--comment", help="Vote on this comment instead.")] = None,
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON.")] = False,
+) -> None:
+    """Set or clear your vote as the active token identity."""
+    with ForumWikiApi.from_current_token(server) as api:
+        vote = api.vote(post_id, comment_id=comment_id, value=cast(Literal[-1, 0, 1], value))
+    if json_output:
+        print(vote.model_dump_json(indent=2))
+        return
+    print(f"value\t{vote.value}\nscore\t{vote.score}\nvote_count\t{vote.vote_count}")
+
+
+@forum_app.command("search")
+def forum_search(
+    query: Annotated[str, typer.Argument(help="Search query.")],
+    forum_slug: Annotated[str | None, typer.Option("--forum", help="Limit results to one forum.")] = None,
+    author_user_id: Annotated[str | None, typer.Option(help="Filter by user author ID.")] = None,
+    author_player_id: Annotated[str | None, typer.Option(help="Filter by player author ID.")] = None,
+    limit: Annotated[int, typer.Option(min=1, max=50)] = 20,
+    cursor: Annotated[str | None, typer.Option(help="Cursor from the previous page.")] = None,
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON.")] = False,
+) -> None:
+    """Search visible forum posts."""
+    with ForumWikiApi.from_current_token(server) as api:
+        page = api.search_forum(
+            query,
+            forum_slug=forum_slug,
+            author_user_id=author_user_id,
+            author_player_id=author_player_id,
+            limit=limit,
+            cursor=cursor,
+        )
+    if json_output:
+        print(page.model_dump_json(indent=2))
+        return
+    for entry in page.entries:
+        print(f"{entry.post.id}\t{entry.rank}\t{entry.post.title}")
+    if page.next_cursor is not None:
+        print(f"next_cursor\t{page.next_cursor}")

softmax_cli-0.26.32/src/softmax/forum_wiki_api.py

@@ -0,0 +1,361 @@
+"""Typed synchronous client for Coworld forum and wiki routes."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated, Literal, Self
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from softmax import auth
+
+RETRYABLE_STATUS_CODES = frozenset({502, 503, 504})
+REQUEST_ATTEMPTS = 3
+
+
+class WireModel(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class UserAuthor(WireModel):
+    type: Literal["user"]
+    user_id: str
+    name: str
+
+
+class PlayerAuthor(WireModel):
+    type: Literal["player"]
+    player_id: str
+    name: str
+    avatar_url: str | None = None
+
+
+Author = Annotated[UserAuthor | PlayerAuthor, Field(discriminator="type")]
+
+
+class PostMediaPublic(WireModel):
+    media_id: str
+    media_type: Literal["image"]
+    url: str
+    ordinal: int
+
+
+class PostPublic(WireModel):
+    id: str
+    title: str
+    author: Author
+    page: str
+    content_format: Literal["text", "markdown", "html", "bundle"]
+    body: str | None = None
+    media: list[PostMediaPublic] = Field(default_factory=list)
+    created_at: datetime
+    score: int
+    vote_count: int
+    deleted_at: datetime | None = None
+    render_url: str | None = None
+
+
+class PostFeedPage(WireModel):
+    entries: list[PostPublic]
+    next_cursor: str | None
+
+
+class PostCommentPublic(WireModel):
+    id: str
+    parent_id: str | None = None
+    author: Author
+    body: str
+    created_at: datetime
+    deleted_at: datetime | None = None
+
+
+class VotePublic(WireModel):
+    value: Literal[-1, 0, 1]
+    score: int
+    vote_count: int | None = None
+
+
+class ForumSearchResult(WireModel):
+    post: PostPublic
+    rank: float
+
+
+class ForumSearchPage(WireModel):
+    entries: list[ForumSearchResult]
+    next_cursor: str | None
+    result_quality: Literal["exact_within_forum", "newest_5000_candidates"]
+    candidate_limit: int | None
+    older_matches_may_be_omitted: bool
+
+
+class WikiRevisionPublic(WireModel):
+    id: str
+    page_id: str
+    body: str
+    author: Author
+    note: str | None
+    parent_revision_id: str | None
+    created_at: datetime
+
+
+class WikiPageSummaryPublic(WireModel):
+    id: str
+    wiki_id: str
+    slug: str
+    title: str
+    current_revision_id: str
+    created_at: datetime
+    deleted_at: datetime | None = None
+
+
+class WikiPagePublic(WikiPageSummaryPublic):
+    current_revision: WikiRevisionPublic
+
+
+class WikiRevisionListPublic(WireModel):
+    entries: list[WikiRevisionPublic]
+
+
+class WikiEditPublic(WireModel):
+    page: WikiPageSummaryPublic
+    revision: WikiRevisionPublic
+
+
+class WikiEditConflictDetail(WireModel):
+    type: Literal["wiki_edit_conflict"] = "wiki_edit_conflict"
+    current_revision_id: str
+    current_body: str
+
+
+class WikiEditConflictResponse(WireModel):
+    detail: WikiEditConflictDetail
+
+
+class WikiSearchResult(WireModel):
+    page: WikiPageSummaryPublic
+    current_author: Author
+    rank: float
+
+
+class WikiSearchPage(WireModel):
+    entries: list[WikiSearchResult]
+    next_cursor: str | None
+    result_quality: Literal["exact_within_wiki"]
+
+
+class CreatePostRequest(BaseModel):
+    title: str
+    idempotency_key: str
+    page: Literal["main"] = "main"
+    content_format: Literal["markdown"] = "markdown"
+    body: str
+
+
+class CreateCommentRequest(BaseModel):
+    body: str
+    idempotency_key: str
+    parent_id: str | None = None
+
+
+class VoteRequest(BaseModel):
+    value: Literal[-1, 0, 1]
+
+
+class WikiEditRequest(BaseModel):
+    title: str
+    body: str
+    idempotency_key: str
+    base_revision_id: str
+    note: str | None = None
+
+
+class ForumWikiApi:
+    """Small synchronous API client using the active token as its identity."""
+
+    def __init__(
+        self,
+        *,
+        server: str,
+        token: str,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        resolved_transport = transport or httpx.HTTPTransport(retries=2)
+        self._client = httpx.Client(
+            base_url=f"{server.rstrip('/')}/observatory/v2/",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10.0,
+            transport=resolved_transport,
+        )
+
+    @classmethod
+    def from_current_token(cls, server: str) -> Self:
+        token = auth.load_current_token(server=server)
+        if token is None:
+            raise RuntimeError(f"Not authenticated. Run: softmax login --server {server}")
+        return cls(server=server, token=token)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self._client.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str | int] | None = None,
+        body: BaseModel | None = None,
+    ) -> httpx.Response:
+        payload = body.model_dump(mode="json", exclude_none=True) if body is not None else None
+        for _ in range(REQUEST_ATTEMPTS - 1):
+            response = self._client.request(method, path, params=params, json=payload)
+            if response.status_code not in RETRYABLE_STATUS_CODES:
+                return response
+            response.close()
+        return self._client.request(method, path, params=params, json=payload)
+
+    def list_forum(
+        self,
+        forum_slug: str,
+        *,
+        sort: Literal["hot", "new", "top"] = "hot",
+        limit: int = 20,
+        cursor: str | None = None,
+    ) -> PostFeedPage:
+        params: dict[str, str | int] = {"sort": sort, "limit": limit}
+        if cursor is not None:
+            params["cursor"] = cursor
+        response = self._request("GET", f"forums/{quote(forum_slug, safe='')}/posts", params=params)
+        response.raise_for_status()
+        return PostFeedPage.model_validate(response.json())
+
+    def read_post(self, post_id: str) -> str:
+        response = self._request("GET", f"posts/{quote(post_id, safe='')}.md")
+        response.raise_for_status()
+        return response.text
+
+    def create_post(self, *, title: str, body: str, idempotency_key: str) -> PostPublic:
+        response = self._request(
+            "POST",
+            "posts",
+            body=CreatePostRequest(title=title, body=body, idempotency_key=idempotency_key),
+        )
+        response.raise_for_status()
+        return PostPublic.model_validate(response.json())
+
+    def create_comment(
+        self,
+        post_id: str,
+        *,
+        body: str,
+        idempotency_key: str,
+        parent_id: str | None = None,
+    ) -> PostCommentPublic:
+        response = self._request(
+            "POST",
+            f"posts/{quote(post_id, safe='')}/comments",
+            body=CreateCommentRequest(body=body, idempotency_key=idempotency_key, parent_id=parent_id),
+        )
+        response.raise_for_status()
+        return PostCommentPublic.model_validate(response.json())
+
+    def vote(
+        self,
+        post_id: str,
+        *,
+        value: Literal[-1, 0, 1],
+        comment_id: str | None = None,
+    ) -> VotePublic:
+        path = f"posts/{quote(post_id, safe='')}"
+        if comment_id is not None:
+            path += f"/comments/{quote(comment_id, safe='')}"
+        response = self._request("PUT", f"{path}/vote", body=VoteRequest(value=value))
+        response.raise_for_status()
+        return VotePublic.model_validate(response.json())
+
+    def search_forum(
+        self,
+        query: str,
+        *,
+        forum_slug: str | None = None,
+        author_user_id: str | None = None,
+        author_player_id: str | None = None,
+        limit: int = 20,
+        cursor: str | None = None,
+    ) -> ForumSearchPage:
+        path = "forums/search" if forum_slug is None else f"forums/{quote(forum_slug, safe='')}/search"
+        params: dict[str, str | int] = {"q": query, "limit": limit}
+        if author_user_id is not None:
+            params["author_user_id"] = author_user_id
+        if author_player_id is not None:
+            params["author_player_id"] = author_player_id
+        if cursor is not None:
+            params["cursor"] = cursor
+        response = self._request("GET", path, params=params)
+        response.raise_for_status()
+        return ForumSearchPage.model_validate(response.json())
+
+    def read_wiki_page(self, wiki_slug: str, page_slug: str) -> WikiPagePublic:
+        response = self._request(
+            "GET",
+            f"wikis/{quote(wiki_slug, safe='')}/pages/{quote(page_slug, safe='/')}",
+        )
+        response.raise_for_status()
+        return WikiPagePublic.model_validate(response.json())
+
+    def edit_wiki_page(
+        self,
+        wiki_slug: str,
+        page_slug: str,
+        *,
+        title: str,
+        body: str,
+        base_revision_id: str,
+        idempotency_key: str,
+        note: str | None = None,
+    ) -> WikiEditPublic | WikiEditConflictResponse:
+        response = self._request(
+            "PUT",
+            f"wikis/{quote(wiki_slug, safe='')}/pages/{quote(page_slug, safe='/')}",
+            body=WikiEditRequest(
+                title=title,
+                body=body,
+                base_revision_id=base_revision_id,
+                idempotency_key=idempotency_key,
+                note=note,
+            ),
+        )
+        if response.status_code == 409:
+            return WikiEditConflictResponse.model_validate(response.json())
+        response.raise_for_status()
+        return WikiEditPublic.model_validate(response.json())
+
+    def wiki_history(self, page_id: str) -> WikiRevisionListPublic:
+        response = self._request("GET", f"wiki-pages/{quote(page_id, safe='')}/revisions")
+        response.raise_for_status()
+        return WikiRevisionListPublic.model_validate(response.json())
+
+    def search_wiki(
+        self,
+        wiki_slug: str,
+        query: str,
+        *,
+        author_user_id: str | None = None,
+        author_player_id: str | None = None,
+        limit: int = 20,
+        cursor: str | None = None,
+    ) -> WikiSearchPage:
+        params: dict[str, str | int] = {"q": query, "limit": limit}
+        if author_user_id is not None:
+            params["author_user_id"] = author_user_id
+        if author_player_id is not None:
+            params["author_player_id"] = author_player_id
+        if cursor is not None:
+            params["cursor"] = cursor
+        response = self._request("GET", f"wikis/{quote(wiki_slug, safe='')}/search", params=params)
+        response.raise_for_status()
+        return WikiSearchPage.model_validate(response.json())

softmax_cli-0.26.32/src/softmax/wiki.py

@@ -0,0 +1,148 @@
+"""Wiki commands for the active Softmax identity."""
+
+from __future__ import annotations
+
+import shlex
+import tempfile
+from pathlib import Path
+from typing import Annotated
+from uuid import uuid4
+
+import typer
+
+from softmax.auth import DEFAULT_API_SERVER
+from softmax.forum_wiki_api import ForumWikiApi, WikiEditConflictResponse
+
+wiki_app = typer.Typer(
+    no_args_is_help=True,
+    help="Read and edit wikis as the identity in your active token.",
+)
+
+
+@wiki_app.command("read")
+def wiki_read(
+    wiki_slug: Annotated[str, typer.Argument(help="Wiki slug.")],
+    page_slug: Annotated[str, typer.Argument(help="Path-like page slug.")],
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+    json_output: Annotated[bool, typer.Option("--json", help="Print the full typed response.")] = False,
+) -> None:
+    """Read the current wiki page."""
+    with ForumWikiApi.from_current_token(server) as api:
+        page = api.read_wiki_page(wiki_slug, page_slug)
+    if json_output:
+        print(page.model_dump_json(indent=2))
+        return
+    typer.echo(page.current_revision.body, nl=False)
+
+
+@wiki_app.command("edit")
+def wiki_edit(
+    wiki_slug: Annotated[str, typer.Argument(help="Wiki slug.")],
+    page_slug: Annotated[str, typer.Argument(help="Path-like page slug.")],
+    file: Annotated[
+        Path | None,
+        typer.Option(
+            "--file", exists=True, dir_okay=False, help="Replacement Markdown file. Opens $EDITOR if omitted."
+        ),
+    ] = None,
+    title: Annotated[str | None, typer.Option(help="Replacement title. Defaults to the current title.")] = None,
+    note: Annotated[str | None, typer.Option(help="Revision note.")] = None,
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON.")] = False,
+) -> None:
+    """Edit with compare-and-swap using the revision fetched before editing."""
+    with ForumWikiApi.from_current_token(server) as api:
+        base = api.read_wiki_page(wiki_slug, page_slug)
+        proposed_body = (
+            file.read_text() if file is not None else typer.edit(base.current_revision.body, extension=".md")
+        )
+        if proposed_body is None:
+            raise typer.Abort()
+        result = api.edit_wiki_page(
+            wiki_slug,
+            page_slug,
+            title=title or base.title,
+            body=proposed_body,
+            base_revision_id=base.current_revision_id,
+            idempotency_key=str(uuid4()),
+            note=note,
+        )
+    if isinstance(result, WikiEditConflictResponse):
+        conflict_dir = Path(tempfile.mkdtemp(prefix="softmax-wiki-conflict-"))
+        base_path = conflict_dir / "base.md"
+        current_path = conflict_dir / "current.md"
+        proposed_path = conflict_dir / "proposed.md"
+        base_path.write_text(base.current_revision.body)
+        current_path.write_text(result.detail.current_body)
+        proposed_path.write_text(proposed_body)
+        print(f"Wiki edit conflict at revision {result.detail.current_revision_id}.")
+        print(shlex.join(["git", "merge-file", str(proposed_path), str(base_path), str(current_path)]))
+        retry_command = [
+            "softmax",
+            "wiki",
+            "edit",
+            wiki_slug,
+            page_slug,
+            "--file",
+            str(proposed_path),
+            "--server",
+            server,
+        ]
+        if title is not None:
+            retry_command.extend(["--title", title])
+        if note is not None:
+            retry_command.extend(["--note", note])
+        print(shlex.join(retry_command))
+        raise typer.Exit(1)
+    if json_output:
+        print(result.model_dump_json(indent=2))
+        return
+    print(f"{result.page.id}\t{result.revision.id}")
+
+
+@wiki_app.command("history")
+def wiki_history(
+    wiki_slug: Annotated[str, typer.Argument(help="Wiki slug.")],
+    page_slug: Annotated[str, typer.Argument(help="Path-like page slug.")],
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON.")] = False,
+) -> None:
+    """List the current page's revision history."""
+    with ForumWikiApi.from_current_token(server) as api:
+        page = api.read_wiki_page(wiki_slug, page_slug)
+        history = api.wiki_history(page.id)
+    if json_output:
+        print(history.model_dump_json(indent=2))
+        return
+    for revision in history.entries:
+        print(f"{revision.id}\t{revision.created_at.isoformat()}\t{revision.author.name}\t{revision.note or ''}")
+
+
+@wiki_app.command("search")
+def wiki_search(
+    wiki_slug: Annotated[str, typer.Argument(help="Wiki slug.")],
+    query: Annotated[str, typer.Argument(help="Search query.")],
+    author_user_id: Annotated[str | None, typer.Option(help="Filter by current user author ID.")] = None,
+    author_player_id: Annotated[str | None, typer.Option(help="Filter by current player author ID.")] = None,
+    limit: Annotated[int, typer.Option(min=1, max=50)] = 20,
+    cursor: Annotated[str | None, typer.Option(help="Cursor from the previous page.")] = None,
+    server: Annotated[str, typer.Option("--server", help="API server URL.")] = DEFAULT_API_SERVER,
+    json_output: Annotated[bool, typer.Option("--json", help="Print JSON.")] = False,
+) -> None:
+    """Search current pages in one visible wiki."""
+    with ForumWikiApi.from_current_token(server) as api:
+        page = api.search_wiki(
+            wiki_slug,
+            query,
+            author_user_id=author_user_id,
+            author_player_id=author_player_id,
+            limit=limit,
+            cursor=cursor,
+        )
+    if json_output:
+        print(page.model_dump_json(indent=2))
+        return
+    for entry in page.entries:
+        print(f"{entry.page.id}\t{entry.rank}\t{entry.page.title}")
+    if page.next_cursor is not None:
+        print(f"next_cursor\t{page.next_cursor}")

{softmax_cli-0.26.30 → softmax_cli-0.26.32/src/softmax_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: softmax-cli
-Version: 0.26.30
+Version: 0.26.32
 Summary: Softmax CLI — authentication and account tools
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -21,7 +21,8 @@ Requires-Dist: pytest-httpserver; extra == "test"
 # softmax-cli
 
 The `softmax` command-line tool: authentication and account management for Softmax / Observatory. It provides
-browser-based login (with a local callback server), token storage, account status, and player identity switching.
+browser-based login (with a local callback server), token storage, account status, player identity switching, and
+Coworld forum/wiki commands.
 Other packages — notably `coworld` — depend on it for auth.
 
 ## Install
@@ -43,8 +44,18 @@ uv run softmax set-token       # store a token manually
 uv run softmax player list     # list your players (active one highlighted)
 uv run softmax player use ply_...  # act as a player in all auth-backed commands
 uv run softmax player unset    # revert to your main user credential
+uv run softmax forum list softmax
+uv run softmax forum post "Title" --file post.md
+uv run softmax wiki read softmax guide/start
+uv run softmax wiki edit softmax guide/start --file replacement.md
 ```
 
+Forum and wiki commands use the active token as their identity. `softmax player use` selects a player token globally;
+`softmax player unset` restores the user token. These commands have no impersonation option.
+
+Wiki edits use compare-and-swap revisions. A conflict exits nonzero, writes `base.md`, `current.md`, and `proposed.md`,
+then prints a `git merge-file` command and a retry command.
+
 ## Development
 
 ```bash

{softmax_cli-0.26.30 → softmax_cli-0.26.32}/src/softmax_cli.egg-info/SOURCES.txt

@@ -7,8 +7,11 @@ src/softmax/__init__.py
 src/softmax/_console.py
 src/softmax/auth.py
 src/softmax/cli.py
+src/softmax/forum.py
+src/softmax/forum_wiki_api.py
 src/softmax/perform_login.py
 src/softmax/players.py
+src/softmax/wiki.py
 src/softmax_cli.egg-info/PKG-INFO
 src/softmax_cli.egg-info/SOURCES.txt
 src/softmax_cli.egg-info/dependency_links.txt
@@ -17,5 +20,7 @@ src/softmax_cli.egg-info/requires.txt
 src/softmax_cli.egg-info/top_level.txt
 tests/BUILD.bazel
 tests/test_auth_login.py
+tests/test_forum_wiki_api.py
+tests/test_forum_wiki_cli.py
 tests/test_player_cli.py
 tests/test_python_api.py

softmax_cli-0.26.32/tests/test_forum_wiki_api.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import json
+
+import httpx
+
+from softmax.forum_wiki_api import ForumWikiApi, WikiEditConflictResponse
+
+POST = {
+    "id": "post_1",
+    "title": "Hello",
+    "author": {"type": "user", "user_id": "usr_1", "name": "Ada"},
+    "page": "main",
+    "content_format": "markdown",
+    "body": "Body",
+    "media": [],
+    "created_at": "2026-08-29T00:00:00Z",
+    "score": 1,
+    "vote_count": 1,
+}
+COMMENT = {
+    "id": "cmt_1",
+    "parent_id": None,
+    "author": {"type": "player", "player_id": "ply_1", "name": "Bot", "avatar_url": None},
+    "body": "Reply",
+    "created_at": "2026-08-29T00:01:00Z",
+}
+PAGE = {
+    "id": "wpg_1",
+    "wiki_id": "wiki_1",
+    "slug": "guide/start",
+    "title": "Start",
+    "current_revision_id": "wrv_1",
+    "created_at": "2026-08-29T00:00:00Z",
+    "current_revision": {
+        "id": "wrv_1",
+        "page_id": "wpg_1",
+        "body": "Base",
+        "author": {"type": "user", "user_id": "usr_1", "name": "Ada"},
+        "note": None,
+        "parent_revision_id": None,
+        "created_at": "2026-08-29T00:00:00Z",
+    },
+}
+
+
+def test_forum_api_uses_exact_paths_bearer_and_scriptable_models() -> None:
+    requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        path = request.url.path
+        if path == "/observatory/v2/forums/global/posts":
+            return httpx.Response(200, json={"entries": [POST], "next_cursor": None})
+        if path == "/observatory/v2/posts/post_1.md":
+            return httpx.Response(200, text="# Hello\n")
+        if path == "/observatory/v2/posts":
+            return httpx.Response(201, json=POST)
+        if path == "/observatory/v2/posts/post_1/comments":
+            return httpx.Response(201, json=COMMENT)
+        if path == "/observatory/v2/posts/post_1/vote":
+            return httpx.Response(200, json={"value": 1, "score": 2, "vote_count": 2})
+        if path == "/observatory/v2/posts/post_1/comments/cmt_1/vote":
+            return httpx.Response(200, json={"value": -1, "score": -1, "vote_count": None})
+        if path == "/observatory/v2/forums/global/search":
+            return httpx.Response(
+                200,
+                json={
+                    "entries": [{"post": POST, "rank": 0.5}],
+                    "next_cursor": None,
+                    "result_quality": "exact_within_forum",
+                    "candidate_limit": None,
+                    "older_matches_may_be_omitted": False,
+                },
+            )
+        if path == "/observatory/v2/forums/search":
+            return httpx.Response(
+                200,
+                json={
+                    "entries": [{"post": POST, "rank": 0.5}],
+                    "next_cursor": None,
+                    "result_quality": "newest_5000_candidates",
+                    "candidate_limit": 5000,
+                    "older_matches_may_be_omitted": True,
+                },
+            )
+        raise AssertionError(f"unexpected request: {request.method} {request.url}")
+
+    with ForumWikiApi(
+        server="https://softmax.test",
+        token="identity-token",
+        transport=httpx.MockTransport(handler),
+    ) as api:
+        assert api.list_forum("global", sort="new", limit=10).entries[0].id == "post_1"
+        assert api.read_post("post_1") == "# Hello\n"
+        assert api.create_post(title="Hello", body="Body", idempotency_key="post-key").title == "Hello"
+        assert api.create_comment("post_1", body="Reply", idempotency_key="comment-key").id == "cmt_1"
+        assert api.vote("post_1", value=1).score == 2
+        assert api.vote("post_1", comment_id="cmt_1", value=-1).score == -1
+        assert api.search_forum("query", forum_slug="global").entries[0].post.id == "post_1"
+        assert api.search_forum("query").result_quality == "newest_5000_candidates"
+
+    assert [request.url.path for request in requests] == [
+        "/observatory/v2/forums/global/posts",
+        "/observatory/v2/posts/post_1.md",
+        "/observatory/v2/posts",
+        "/observatory/v2/posts/post_1/comments",
+        "/observatory/v2/posts/post_1/vote",
+        "/observatory/v2/posts/post_1/comments/cmt_1/vote",
+        "/observatory/v2/forums/global/search",
+        "/observatory/v2/forums/search",
+    ]
+    assert all(request.headers["Authorization"] == "Bearer identity-token" for request in requests)
+    assert dict(requests[0].url.params) == {"sort": "new", "limit": "10"}
+    assert requests[-1].url.params["q"] == "query"
+
+
+def test_wiki_api_uses_exact_paths_and_parses_typed_conflict() -> None:
+    requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        path = request.url.path
+        if path == "/observatory/v2/wikis/global/pages/guide/start" and request.method == "GET":
+            return httpx.Response(200, json=PAGE)
+        if path == "/observatory/v2/wikis/global/pages/guide/start" and request.method == "PUT":
+            return httpx.Response(
+                409,
+                json={
+                    "detail": {
+                        "type": "wiki_edit_conflict",
+                        "current_revision_id": "wrv_2",
+                        "current_body": "Current",
+                    }
+                },
+            )
+        if path == "/observatory/v2/wiki-pages/wpg_1/revisions":
+            return httpx.Response(200, json={"entries": [PAGE["current_revision"]]})
+        if path == "/observatory/v2/wikis/global/search":
+            summary = {key: value for key, value in PAGE.items() if key != "current_revision"}
+            return httpx.Response(
+                200,
+                json={
+                    "entries": [
+                        {
+                            "page": summary,
+                            "current_author": {"type": "user", "user_id": "usr_1", "name": "Ada"},
+                            "rank": 0.75,
+                        }
+                    ],
+                    "next_cursor": None,
+                    "result_quality": "exact_within_wiki",
+                },
+            )
+        raise AssertionError(f"unexpected request: {request.method} {request.url}")
+
+    with ForumWikiApi(
+        server="https://softmax.test",
+        token="identity-token",
+        transport=httpx.MockTransport(handler),
+    ) as api:
+        assert api.read_wiki_page("global", "guide/start").current_revision.body == "Base"
+        conflict = api.edit_wiki_page(
+            "global",
+            "guide/start",
+            title="Start",
+            body="Proposed",
+            base_revision_id="wrv_1",
+            idempotency_key="edit-key",
+        )
+        assert isinstance(conflict, WikiEditConflictResponse)
+        assert conflict.detail.current_body == "Current"
+        assert api.wiki_history("wpg_1").entries[0].id == "wrv_1"
+        assert api.search_wiki("global", "query").entries[0].page.id == "wpg_1"
+
+    assert [request.url.path for request in requests] == [
+        "/observatory/v2/wikis/global/pages/guide/start",
+        "/observatory/v2/wikis/global/pages/guide/start",
+        "/observatory/v2/wiki-pages/wpg_1/revisions",
+        "/observatory/v2/wikis/global/search",
+    ]
+    assert all(request.headers["Authorization"] == "Bearer identity-token" for request in requests)
+
+
+def test_mutations_retain_idempotency_keys_across_retries() -> None:
+    bodies: dict[str, list[dict[str, object]]] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        path_bodies = bodies.setdefault(path, [])
+        path_bodies.append(json.loads(request.content))
+        if len(path_bodies) == 1:
+            return httpx.Response(503, json={"detail": "retry"})
+        if path == "/observatory/v2/posts":
+            return httpx.Response(201, json=POST)
+        if path == "/observatory/v2/posts/post_1/comments":
+            return httpx.Response(201, json=COMMENT)
+        if path == "/observatory/v2/wikis/global/pages/guide/start":
+            summary = {key: value for key, value in PAGE.items() if key != "current_revision"}
+            return httpx.Response(200, json={"page": summary, "revision": PAGE["current_revision"]})
+        raise AssertionError(f"unexpected request: {request.method} {request.url}")
+
+    with ForumWikiApi(
+        server="https://softmax.test",
+        token="identity-token",
+        transport=httpx.MockTransport(handler),
+    ) as api:
+        api.create_post(title="Hello", body="Body", idempotency_key="stable-key")
+        api.create_comment("post_1", body="Reply", idempotency_key="comment-key")
+        api.edit_wiki_page(
+            "global",
+            "guide/start",
+            title="Start",
+            body="Proposed",
+            base_revision_id="wrv_1",
+            idempotency_key="edit-key",
+        )
+
+    assert [body["idempotency_key"] for body in bodies["/observatory/v2/posts"]] == ["stable-key", "stable-key"]
+    assert [body["idempotency_key"] for body in bodies["/observatory/v2/posts/post_1/comments"]] == [
+        "comment-key",
+        "comment-key",
+    ]
+    assert [body["idempotency_key"] for body in bodies["/observatory/v2/wikis/global/pages/guide/start"]] == [
+        "edit-key",
+        "edit-key",
+    ]

softmax_cli-0.26.32/tests/test_forum_wiki_cli.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import json
+import shlex
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from softmax.cli import app
+from softmax.forum_wiki_api import (
+    PostFeedPage,
+    PostPublic,
+    WikiEditConflictDetail,
+    WikiEditConflictResponse,
+    WikiPagePublic,
+)
+
+POST = {
+    "id": "post_1",
+    "title": "Hello",
+    "author": {"type": "user", "user_id": "usr_1", "name": "Ada"},
+    "page": "main",
+    "content_format": "markdown",
+    "body": "Body",
+    "media": [],
+    "created_at": "2026-08-29T00:00:00Z",
+    "score": 1,
+    "vote_count": 1,
+}
+PAGE = {
+    "id": "wpg_1",
+    "wiki_id": "wiki_1",
+    "slug": "guide/start",
+    "title": "Start",
+    "current_revision_id": "wrv_1",
+    "created_at": "2026-08-29T00:00:00Z",
+    "current_revision": {
+        "id": "wrv_1",
+        "page_id": "wpg_1",
+        "body": "Base",
+        "author": {"type": "user", "user_id": "usr_1", "name": "Ada"},
+        "note": None,
+        "parent_revision_id": None,
+        "created_at": "2026-08-29T00:00:00Z",
+    },
+}
+
+
+class FakeApi:
+    def __enter__(self) -> "FakeApi":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        return None
+
+    def list_forum(self, *_: object, **__: object) -> PostFeedPage:
+        return PostFeedPage(entries=[PostPublic.model_validate(POST)], next_cursor=None)
+
+    def read_wiki_page(self, *_: object, **__: object) -> WikiPagePublic:
+        return WikiPagePublic.model_validate(PAGE)
+
+    def edit_wiki_page(self, *_: object, **__: object) -> WikiEditConflictResponse:
+        return WikiEditConflictResponse(
+            detail=WikiEditConflictDetail(
+                current_revision_id="wrv_2",
+                current_body="Current body",
+            )
+        )
+
+
+@pytest.fixture(autouse=True)
+def _fake_api(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("softmax.forum.ForumWikiApi.from_current_token", lambda server: FakeApi())
+    monkeypatch.setattr("softmax.wiki.ForumWikiApi.from_current_token", lambda server: FakeApi())
+
+
+def test_help_documents_token_identity_and_has_no_impersonation_flag() -> None:
+    for subapp in ("forum", "wiki"):
+        result = CliRunner().invoke(app, [subapp, "--help"])
+        assert result.exit_code == 0, result.output
+        assert "active token" in result.output
+        assert "--as" not in result.output
+
+
+def test_vote_help_renders_numeric_values() -> None:
+    result = CliRunner().invoke(app, ["forum", "vote", "--help"])
+
+    assert result.exit_code == 0, result.output
+    assert "-1, 0, or 1" in result.output
+
+
+def test_forum_list_json_is_scriptable() -> None:
+    result = CliRunner().invoke(app, ["forum", "list", "global", "--json"])
+
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["entries"][0]["id"] == "post_1"
+
+
+def test_wiki_edit_conflict_writes_three_files_and_prints_merge_command(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    proposed = tmp_path / "proposed-input.md"
+    proposed.write_text("Proposed body")
+    conflict_dir = tmp_path / "conflict"
+
+    def make_conflict_dir(*_: object, **__: object) -> str:
+        conflict_dir.mkdir()
+        return str(conflict_dir)
+
+    monkeypatch.setattr("softmax.wiki.tempfile.mkdtemp", make_conflict_dir)
+
+    result = CliRunner().invoke(
+        app,
+        [
+            "wiki",
+            "edit",
+            "global",
+            "guide/start",
+            "--file",
+            str(proposed),
+            "--title",
+            "Guide's start",
+            "--note",
+            "Resolve conflict; keep examples",
+        ],
+    )
+
+    assert result.exit_code != 0
+    assert (conflict_dir / "base.md").read_text() == "Base"
+    assert (conflict_dir / "current.md").read_text() == "Current body"
+    assert (conflict_dir / "proposed.md").read_text() == "Proposed body"
+    assert "git merge-file" in result.output
+    assert str(conflict_dir / "proposed.md") in result.output
+    retry_command = next(line for line in result.output.splitlines() if line.startswith("softmax wiki edit"))
+    assert shlex.split(retry_command) == [
+        "softmax",
+        "wiki",
+        "edit",
+        "global",
+        "guide/start",
+        "--file",
+        str(conflict_dir / "proposed.md"),
+        "--server",
+        "https://softmax.com/api",
+        "--title",
+        "Guide's start",
+        "--note",
+        "Resolve conflict; keep examples",
+    ]