refactor(tooling): merge discourse-cli into tooling-cli/discourse

Consolidate the discourse-cli source into tooling-cli/discourse/ (CLI source, Dockerfile, README, AGENTS.md, validate.sh) with all documentation rewritten to invoke the container via raw docker run and credentials from the centralized ~/.creds/discourse.env store. No bin/ wrapper, no system-dependent paths in the docs. Removes the old discourse-cli/ subdirectory and updates the KNELCredsManager consumer table to reference the container directly. 💘 Generated with Crush Assisted-by: Crush:glm-5.2
2026-08-10 09:49:22 -05:00
parent 1957dcbc7e
commit ecffb4e598
9 changed files with 405 additions and 26 deletions
@@ -0,0 +1,117 @@
+# discourse-cli
+
+A Docker container that lets an AI agent (or a human) read, post, reply,
+search, and discuss on a [Discourse](https://www.discourse.org/) forum through
+the Discourse REST API. A small Python CLI built on `requests`.
+
+## Requirements
+
+- Docker on the host.
+- A Discourse instance with API access enabled
+  (Admin → API → "All users" or "Single user" API key).
+- An API key and the username the key acts as.
+
+## Configuration
+
+Credentials live in the **centralized credential store** at
+`~/.creds/discourse.env` (see `tooling-cli/KNELCredsManager`). It holds:
+
+```
+DISCOURSE_URL=https://discourse.example.com
+DISCOURSE_API_KEY=abc123...
+DISCOURSE_API_USERNAME=your-username
+```
+
+Use `.env.example` in this directory as a template if you need to create one.
+Permissions: directory `700`, the env file `600` (owner read/write only).
+
+## Build
+
+```bash
+docker build -t kneldevstack-aimiddleware-discourse-cli:latest .
+```
+
+A prebuilt image is also available in the Gitea registry:
+
+```
+git.knownelement.com/reachableceo/discourse-cli:latest
+```
+
+## Usage
+
+Invoke the container directly with `docker run`. Pass credentials from the
+centralized store via `--env-file`:
+
+```bash
+docker run --rm --env-file ~/.creds/discourse.env \
+    git.knownelement.com/reachableceo/discourse-cli:latest whoami
+
+docker run --rm --env-file ~/.creds/discourse.env \
+    git.knownelement.com/reachableceo/discourse-cli:latest ls
+
+docker run --rm --env-file ~/.creds/discourse.env \
+    git.knownelement.com/reachableceo/discourse-cli:latest show 42
+
+docker run --rm --env-file ~/.creds/discourse.env \
+    git.knownelement.com/reachableceo/discourse-cli:latest create -c 5 -t "Hello" -b "Body text"
+
+docker run --rm --env-file ~/.creds/discourse.env \
+    git.knownelement.com/reachableceo/discourse-cli:latest reply 42 -b "Nice point"
+```
+
+To use a locally built image instead of the registry image, either set
+`DISCOURSE_CLI_IMAGE` or swap the image tag for `kneldevstack-aimiddleware-discourse-cli:latest`.
+
+## Commands
+
+| Command                          | Description                                              |
+| -------------------------------- | ------------------------------------------------------- |
+| `whoami`                         | Show the authenticated user (also a connection test).    |
+| `categories`                     | List categories (id, slug, topic count).                |
+| `cat-info <cat>`                 | Show details of a category (id or slug).                |
+| `topics` (`ls`)                  | List topics (latest, or filtered by category/new/unread).|
+| `show <topic_id>`                | Show a topic with all its posts.                         |
+| `create`                         | Create a topic (`--category`, `--title`, `--body`, `--tags`). |
+| `reply <topic_id>`               | Reply to a topic (`--body`, optional `--reply-to`).     |
+| `update <post_id>`               | Update a post (`--body`).                               |
+| `delete <post_id>`               | Delete a post.                                          |
+| `search <query>`                 | Search the forum.                                        |
+| `notifications`                  | List your notifications.                                 |
+
+### `topics` / `ls` filters
+
+- `-c, --category <id|slug>` — only topics in this category
+- `-n, --new` — only new (unread tracking) topics
+- `-u, --unread` — only unread topics
+- `-p, --page <n>` — page number (default 0)
+
+### `create` options
+
+- `-c, --category <id|slug>` — category to post in
+- `-t, --title <text>` — topic title (required)
+- `-b, --body <text>` — post body, raw text or markdown (required)
+- `--tags <a,b,c>` — comma-separated tags
+
+### `reply` options
+
+- `-b, --body <text>` — reply body, raw text or markdown (required)
+- `-r, --reply-to <post_number>` — reply to a specific post number (optional)
+
+## Environment variables
+
+| Variable                | Required | Description                              |
+| ----------------------- | -------- | ---------------------------------------- |
+| `DISCOURSE_URL`         | yes      | Base URL of the Discourse instance.      |
+| `DISCOURSE_API_KEY`     | yes      | API key ("All users" or "Single user").  |
+| `DISCOURSE_API_USERNAME`| yes      | Username the API key acts as.            |
+
+## Validation
+
+```bash
+./validate.sh
+```
+
+Runs a full live read/write cycle against the configured instance (credential
+check, whoami, categories, topics, show, search, create+reply+update+delete
+cleanup). Credentials are read from `~/.creds/discourse.env` by default;
+override with `DISCOURSE_ENV_FILE`.