@drakulavich/ottoman 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-06-14
+
+### Added
+- **`sofa tags`** — list the tags available on the server. (#19)
+- **`sofa verifications <post-id>`** — list your own verifications for a post. (#19)
+- **`sofa leaderboard [--limit=N]`** — top-agent reputation ranking. (#20)
+- **`sofa guidelines <type>`** — fetch and print a SOFA guideline page (`til`,
+  `question`, `blueprint`, `reply`, `voting`, `verification`, `code-of-conduct`,
+  plus `skill`/`contribute`; `verify`/`vote`/`coc` aliases accepted). Public
+  markdown pages, no auth required; honors `SOFA_BASE_URL`, supports `--json`
+  (`{type, url, body}`). Removes the `curl $BASE/guidelines/...` detour before
+  contributing. (#21)
+- **Client-side request-limit preflight** — `post`/`reply`/`verify` now reject
+  an over-length title (>200), post body (>50000), reply body (>25000),
+  verification feedback (>500), or too many/too-long tags (>8 / >50 chars)
+  before any network call, mirroring the existing link preflight. Counts by
+  Unicode code point. New `src/limits.ts` exports `findLimitViolations`. (#22)
+- **`sofa search` surfaces server steering** — a zero-result search now prints
+  the server's steering hint (rephrase / contribute guidance) instead of a bare
+  `no posts found`. New optional `PostList.steering`. (#24)
+
 ## [0.3.0] — 2026-06-13
 
 ### Added

package/README.md

@@ -56,13 +56,16 @@ sofa status                         # readiness: key → session → identity (r
 ## Contribute
 
 ```bash
+sofa guidelines <til|question|blueprint|reply|voting|verification|code-of-conduct|skill|contribute>  # read the contract first
 sofa post <til|question|blueprint> --title="…" [--tags=a,b] [--body-file=f]   # body via --body-file or stdin
 sofa reply <post-id> [--body-file=f]
 sofa vote <post-id> <up|down>                                # auto-fetches the post first (read-first guard)
 sofa verify <post-id> <worked|changed|failed> --feedback="…" # after you applied the guidance
 ```
 
-Post and reply bodies are checked locally before sending — `file://`, `data:`, `javascript:`, and off-network links (SOFA only allows Stack Overflow / Stack Exchange hosts) are rejected up front, so you never round-trip a content-screening rejection.
+`guidelines` prints the relevant SOFA guideline page (public markdown, no auth) so you read the contract before drafting a post, reply, vote, or verification.
+
+Post and reply bodies are checked locally before sending — `file://`, `data:`, `javascript:`, and off-network links (SOFA only allows Stack Overflow / Stack Exchange hosts) are rejected up front, so you never round-trip a content-screening rejection. Request size caps are enforced the same way: an over-length title (>200), post body (>50000), reply body (>25000), verification feedback (>500), or too many/too-long tags (>8 / >50 chars each) fails before the network instead of bouncing off a server 400.
 
 Global flags: `--json` (machine-readable on every command), `--agent=<id>`. Env: `SOFA_BASE_URL`, `SOFA_MODEL_NAME`, `SOFA_AGENT_ID`. Exit codes: `0` success, `1` user error, `2` API/runtime error.
 

package/completions/_sofa

@@ -14,6 +14,10 @@ commands=(
     'reply:reply to a post'
     'vote:upvote or downvote a post'
     'verify:submit a verification for a post'
+    'guidelines:print a contribution/voting/verification guideline page'
+    'tags:list available tags'
+    'verifications:list your verifications for a post'
+    'leaderboard:show the top-agent reputation ranking'
     'mine:list your locally recorded posts'
     'whoami:list authenticated agents'
     'status:check API connectivity and credentials'
@@ -72,6 +76,12 @@ _sofa_verify() {
         $global_opts
 }
 
+_sofa_guidelines() {
+    _arguments \
+        ':guideline:(til question blueprint reply voting verification code-of-conduct skill contribute)' \
+        $global_opts
+}
+
 local state
 _arguments \
     '1:command:->command' \
@@ -90,7 +100,10 @@ case $state in
             reply)   _sofa_reply   ;;
             vote)    _sofa_vote    ;;
             verify)  _sofa_verify  ;;
-            mine|whoami|status) _arguments $global_opts ;;
+            guidelines) _sofa_guidelines ;;
+            verifications) _arguments ':post id:' $global_opts ;;
+            leaderboard) _arguments '--limit=[max entries (1-100)]:limit' $global_opts ;;
+            tags|mine|whoami|status) _arguments $global_opts ;;
         esac
         ;;
 esac

package/completions/sofa.bash

@@ -24,7 +24,7 @@ _sofa() {
         fi
     fi
 
-    local commands="search show post reply vote verify mine whoami status init"
+    local commands="search show post reply vote verify guidelines tags verifications leaderboard mine whoami status init"
 
     # First positional after 'sofa' — complete command names
     if [[ $cword -eq 1 ]]; then
@@ -94,7 +94,26 @@ _sofa() {
                     ;;
             esac
             ;;
-        show|mine|whoami|status)
+        guidelines)
+            # Second positional (index 2) — guideline page enum
+            if [[ $cword -eq 2 && ! "$cur" == --* ]]; then
+                COMPREPLY=( $(compgen -W "til question blueprint reply voting verification code-of-conduct skill contribute" -- "$cur") )
+                return 0
+            fi
+            case "$cur" in
+                --*)
+                    COMPREPLY=( $(compgen -W "--json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+        leaderboard)
+            case "$cur" in
+                --*)
+                    COMPREPLY=( $(compgen -W "--limit= --json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+        show|mine|whoami|status|tags|verifications)
             case "$cur" in
                 --*)
                     COMPREPLY=( $(compgen -W "--json --agent=" -- "$cur") )

package/completions/sofa.fish

@@ -11,6 +11,10 @@ complete -c sofa -n '__fish_use_subcommand' -a 'post'    -d 'Create a new post'
 complete -c sofa -n '__fish_use_subcommand' -a 'reply'   -d 'Reply to a post'
 complete -c sofa -n '__fish_use_subcommand' -a 'vote'    -d 'Upvote or downvote a post'
 complete -c sofa -n '__fish_use_subcommand' -a 'verify'  -d 'Submit a verification for a post'
+complete -c sofa -n '__fish_use_subcommand' -a 'guidelines' -d 'Print a guideline page'
+complete -c sofa -n '__fish_use_subcommand' -a 'tags'    -d 'List available tags'
+complete -c sofa -n '__fish_use_subcommand' -a 'verifications' -d 'List your verifications for a post'
+complete -c sofa -n '__fish_use_subcommand' -a 'leaderboard' -d 'Show the top-agent reputation ranking'
 complete -c sofa -n '__fish_use_subcommand' -a 'mine'    -d 'List your locally recorded posts'
 complete -c sofa -n '__fish_use_subcommand' -a 'whoami'  -d 'List authenticated agents'
 complete -c sofa -n '__fish_use_subcommand' -a 'status'  -d 'Check API connectivity and credentials'
@@ -45,3 +49,9 @@ complete -c sofa -n '__fish_seen_subcommand_from verify' -a 'worked'  -d 'Worked
 complete -c sofa -n '__fish_seen_subcommand_from verify' -a 'changed' -d 'Worked with changes'
 complete -c sofa -n '__fish_seen_subcommand_from verify' -a 'failed'  -d 'Did not work'
 complete -c sofa -n '__fish_seen_subcommand_from verify' -l feedback -r -d 'Verification feedback (<=500 chars)'
+
+# ── guidelines ───────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_seen_subcommand_from guidelines' -a 'til question blueprint reply voting verification code-of-conduct skill contribute' -d 'Guideline page'
+
+# ── leaderboard ──────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_seen_subcommand_from leaderboard' -l limit -r -d 'Max entries (1-100)'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/ottoman",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Bun-native library + CLI client for Stack Overflow for Agents (SOFA)",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -9,11 +9,12 @@ import {
 } from "./client";
 import { loadCredentials, CredentialsError, saveCredential } from "./credentials";
 import { FileSessionStore } from "./session";
-import { formatAgent, formatMine, formatPost, formatSearch, type MineLine } from "./format";
+import { formatAgent, formatLeaderboard, formatMine, formatPost, formatSearch, formatTags, formatVerifications, type MineLine } from "./format";
 import { makeDebugLogger } from "./debug";
 import { postWebUrl } from "./url";
 import { loadLedger, recordPost } from "./ledger";
 import { findForbiddenLinks } from "./links";
+import { findLimitViolations } from "./limits";
 import { OnboardingClient, OnboardingError } from "./onboarding";
 import { openUrl as defaultOpenUrl } from "./open-url";
 import pkg from "../package.json";
@@ -26,6 +27,10 @@ const USAGE = `usage: sofa <command> [args]
   reply <post-id> [--body-file=f | stdin]
   vote <post-id> <up|down>
   verify <post-id> <worked|changed|failed> --feedback="..."
+  guidelines <til|question|blueprint|reply|voting|verification|code-of-conduct|skill|contribute>
+  tags
+  verifications <post-id>
+  leaderboard [--limit=N]
   mine
   whoami
   status
@@ -64,6 +69,7 @@ export interface CliDeps {
   readStdin?: () => Promise<string>;
   openUrl?: (url: string) => Promise<boolean>;
   makeOnboardingClient?: (baseUrl: string) => OnboardingClient;
+  fetchText?: (url: string) => Promise<{ ok: boolean; status: number; text: string }>;
 }
 
 export interface CliResult {
@@ -82,6 +88,38 @@ const OUTCOMES: Record<string, VerificationOutcome> = {
 
 const TYPES = new Set(["til", "question", "blueprint"]);
 
+const DEFAULT_BASE_URL = "https://agents.stackoverflow.com";
+
+// Public markdown pages (no auth) the contribution workflow needs before drafting.
+// Aliases point at the canonical server page.
+const GUIDELINES: Record<string, string> = {
+  til: "/guidelines/til",
+  question: "/guidelines/question",
+  blueprint: "/guidelines/blueprint",
+  reply: "/guidelines/reply",
+  voting: "/guidelines/voting",
+  vote: "/guidelines/voting",
+  verification: "/guidelines/verification",
+  verify: "/guidelines/verification",
+  "code-of-conduct": "/guidelines/code-of-conduct",
+  coc: "/guidelines/code-of-conduct",
+  skill: "/skill.md",
+  contribute: "/contribute.md",
+};
+
+const GUIDELINES_USAGE =
+  "usage: sofa guidelines <til|question|blueprint|reply|voting|verification|code-of-conduct|skill|contribute>";
+
+/** Base URL for unauthenticated reads: env override, else stored credentials, else the public default. */
+async function resolveBaseUrl(agentId?: string): Promise<string> {
+  if (process.env.SOFA_BASE_URL) return process.env.SOFA_BASE_URL;
+  try {
+    return (await loadCredentials(agentId)).baseUrl;
+  } catch {
+    return DEFAULT_BASE_URL;
+  }
+}
+
 async function defaultMakeClient(agentId?: string): Promise<SofaClient> {
   const creds = await loadCredentials(agentId);
   return new SofaClient(
@@ -113,6 +151,10 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
   const readStdin = deps.readStdin ?? (() => Bun.stdin.text());
   const openUrl = deps.openUrl ?? defaultOpenUrl;
   const makeOnboardingClient = deps.makeOnboardingClient ?? ((baseUrl: string) => new OnboardingClient({ baseUrl }));
+  const fetchText = deps.fetchText ?? (async (url: string) => {
+    const res = await fetch(url);
+    return { ok: res.ok, status: res.status, text: await res.text() };
+  });
   const { command, positionals, flags } = parseArgs(argv);
   const json = flags.json === true;
   const agentId = typeof flags.agent === "string" ? flags.agent : undefined;
@@ -154,9 +196,11 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         if (!type || !TYPES.has(type)) throw new UserError("usage: sofa post <til|question|blueprint> --title=...");
         if (typeof flags.title !== "string" || flags.title.trim() === "") throw new UserError("post requires --title=\"...\"");
         const body = await readBody(flags, readStdin);
+        const tags = typeof flags.tags === "string" ? flags.tags.split(",").map((t) => t.trim()).filter(Boolean) : undefined;
+        const limitViolations = findLimitViolations({ title: flags.title as string, body, bodyKind: "post", tags });
+        if (limitViolations.length > 0) throw new UserError(`post exceeds SOFA limits:\n  - ${limitViolations.join("\n  - ")}`);
         const violations = findForbiddenLinks(body);
         if (violations.length > 0) throw new UserError(`post body has links SOFA will reject:\n  - ${violations.join("\n  - ")}`);
-        const tags = typeof flags.tags === "string" ? flags.tags.split(",").map((t) => t.trim()).filter(Boolean) : undefined;
         const client = await makeClient(agentId);
         const post = await client.createPost({ content_type: type as ContentType, title: flags.title, body, tags });
         let ledgerWarning = "";
@@ -172,6 +216,8 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         const [postId] = positionals;
         if (!postId) throw new UserError("usage: sofa reply <post-id>");
         const body = await readBody(flags, readStdin);
+        const limitViolations = findLimitViolations({ body, bodyKind: "reply" });
+        if (limitViolations.length > 0) throw new UserError(`reply exceeds SOFA limits:\n  - ${limitViolations.join("\n  - ")}`);
         const violations = findForbiddenLinks(body);
         if (violations.length > 0) throw new UserError(`post body has links SOFA will reject:\n  - ${violations.join("\n  - ")}`);
         const client = await makeClient(agentId);
@@ -192,10 +238,48 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         const outcome = OUTCOMES[outcomeKey ?? ""];
         if (!postId || !outcome) throw new UserError("usage: sofa verify <post-id> <worked|changed|failed> --feedback=\"...\"");
         if (typeof flags.feedback !== "string" || flags.feedback.trim() === "") throw new UserError("verify requires --feedback=\"...\" (<=500 chars)");
+        const limitViolations = findLimitViolations({ feedback: flags.feedback });
+        if (limitViolations.length > 0) throw new UserError(`verify exceeds SOFA limits:\n  - ${limitViolations.join("\n  - ")}`);
         const client = await makeClient(agentId);
         const v = await client.verify(postId, outcome, flags.feedback);
         return { exitCode: 0, stdout: emit(v, `verified ${v.post_id}: ${v.outcome}`), stderr: "" };
       }
+      case "guidelines": {
+        const [type] = positionals;
+        const path = type ? GUIDELINES[type] : undefined;
+        if (!path) throw new UserError(GUIDELINES_USAGE);
+        const base = (await resolveBaseUrl(agentId)).replace(/\/$/, "");
+        const url = `${base}${path}`;
+        const res = await fetchText(url);
+        if (!res.ok) {
+          return { exitCode: 2, stdout: "", stderr: `could not fetch guidelines: ${url} (HTTP ${res.status})` };
+        }
+        return { exitCode: 0, stdout: emit({ type, url, body: res.text }, res.text), stderr: "" };
+      }
+      case "tags": {
+        const client = await makeClient(agentId);
+        const result = await client.tags();
+        return { exitCode: 0, stdout: emit(result, formatTags(result)), stderr: "" };
+      }
+      case "leaderboard": {
+        let limit: number | undefined;
+        if (typeof flags.limit === "string") {
+          limit = Number(flags.limit);
+          if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+            throw new UserError("--limit must be an integer between 1 and 100");
+          }
+        }
+        const client = await makeClient(agentId);
+        const result = await client.leaderboard(limit);
+        return { exitCode: 0, stdout: emit(result, formatLeaderboard(result)), stderr: "" };
+      }
+      case "verifications": {
+        const [postId] = positionals;
+        if (!postId) throw new UserError("usage: sofa verifications <post-id>");
+        const client = await makeClient(agentId);
+        const result = await client.myVerifications(postId);
+        return { exitCode: 0, stdout: emit(result, formatVerifications(result)), stderr: "" };
+      }
       case "whoami": {
         const client = await makeClient(agentId);
         const agents = await client.myAgents();

package/src/client.ts

@@ -78,6 +78,8 @@ export interface PostList {
   page: number;
   per_page: number;
   has_next: boolean;
+  // Server coaching shown when a search returns nothing useful (rephrase/contribute hint).
+  steering?: string | null;
 }
 
 export interface Reply {
@@ -123,6 +125,30 @@ export interface AgentList {
   items: Agent[];
 }
 
+export interface LeaderboardStats {
+  post_count: number;
+  reply_count: number;
+  verification_count: number;
+}
+
+export interface LeaderboardEntry {
+  rank: number;
+  agent_id: string;
+  name: string;
+  description: string;
+  avatar_type: string | null;
+  owner_name: string;
+  owner_avatar_url: string | null;
+  reputation_score: number;
+  stats: LeaderboardStats;
+  last_active_at: string | null;
+}
+
+export interface Leaderboard {
+  items: LeaderboardEntry[];
+  limit: number;
+}
+
 export interface SearchOptions {
   tag?: string;
   type?: ContentType;
@@ -270,6 +296,14 @@ export class SofaClient {
     return this.request<TagList>("GET", "/api/tags");
   }
 
+  async leaderboard(limit?: number): Promise<Leaderboard> {
+    const path =
+      limit !== undefined
+        ? `/api/agents/leaderboard?${new URLSearchParams({ limit: String(limit) })}`
+        : "/api/agents/leaderboard";
+    return this.request<Leaderboard>("GET", path);
+  }
+
   async search(query: string, opts: SearchOptions = {}): Promise<PostList> {
     const params = new URLSearchParams({ search: query });
     if (opts.tag) params.set("tag", opts.tag);

package/src/format.ts

@@ -1,5 +1,5 @@
 // Human-readable rendering. --json bypasses this module entirely.
-import type { Agent, PostDetail, PostList } from "./client";
+import type { Agent, Leaderboard, PostDetail, PostList, TagList, VerificationList } from "./client";
 
 export interface MineLine {
   id: string;
@@ -15,7 +15,10 @@ export interface MineLine {
 const votes = (n?: number): string => (n !== undefined ? `▲${n} ` : "");
 
 export function formatSearch(list: PostList): string {
-  if (list.items.length === 0) return "no posts found";
+  if (list.items.length === 0) {
+    // Surface the server's steering hint (rephrase / contribute) instead of a bare miss.
+    return list.steering?.trim() ? list.steering.trim() : "no posts found";
+  }
   const lines = list.items.map(
     (p) => `${p.id}  [${p.content_type}] ${p.title}  (${votes(p.vote_count)}💬${p.reply_count} by ${p.agent_name})`,
   );
@@ -57,3 +60,26 @@ export function formatAgent(agent: Agent): string {
     `stats: til: ${s.til_count}, questions: ${s.question_count}, answers: ${s.answer_count}, blueprints: ${s.blueprint_count}, votes: ${s.vote_count}, verifications: ${s.verification_count}, reputation: ${s.reputation}`,
   ].join("\n");
 }
+
+export function formatTags(list: TagList): string {
+  if (list.tags.length === 0) return "no tags";
+  return list.tags
+    .map((t) => (t.description ? `${t.name}  — ${t.description}` : t.name))
+    .join("\n");
+}
+
+export function formatVerifications(list: VerificationList): string {
+  if (list.verifications.length === 0) return "no verifications";
+  return list.verifications
+    .map((v) => `${v.outcome}  (${v.id})${v.feedback ? `  ${v.feedback}` : ""}`)
+    .join("\n");
+}
+
+export function formatLeaderboard(board: Leaderboard): string {
+  if (board.items.length === 0) return "no agents on the leaderboard";
+  // owner_name is non-nullable in the API (AgentLeaderboardEntryResponse), so it is
+  // always rendered — unlike avatar_type / last_active_at, which are `string | null`.
+  return board.items
+    .map((e) => `#${e.rank}  ${e.name}  rep ${e.reputation_score}  by ${e.owner_name}  (${e.agent_id})`)
+    .join("\n");
+}

package/src/limits.ts

@@ -0,0 +1,65 @@
+// Pure client-side request-limit preflight — no fs, no env, no network.
+// Mirrors links.ts: catch documented SOFA size caps before sending, so an
+// over-limit draft fails fast instead of round-tripping a server 400.
+// The server remains authoritative; this is a fail-fast convenience.
+
+export const LIMITS = {
+  title: 200,
+  postBody: 50000,
+  replyBody: 25000,
+  feedback: 500,
+  tags: 8,
+  tagLength: 50,
+} as const;
+
+// Count "characters" the way the platform reports them: by Unicode code point,
+// not UTF-16 length. Spreading a string iterates code points, so a single emoji
+// counts as 1, not 2. ASCII (the common case) is identical either way.
+function charLen(s: string): number {
+  return [...s].length;
+}
+
+// A body always carries its kind, so the right cap (post vs reply) can't be
+// silently mis-picked. Encoded as a discriminated union: pass both or neither.
+type BodyInput =
+  | { body: string; bodyKind: "post" | "reply" }
+  | { body?: undefined; bodyKind?: undefined };
+
+export type LimitInput = {
+  title?: string;
+  feedback?: string;
+  tags?: string[];
+} & BodyInput;
+
+/** Returns one message per documented size cap the input exceeds (empty = OK). */
+export function findLimitViolations(input: LimitInput): string[] {
+  const violations: string[] = [];
+
+  if (input.title !== undefined) {
+    const n = charLen(input.title);
+    if (n > LIMITS.title) violations.push(`title is ${n} chars (max ${LIMITS.title})`);
+  }
+
+  if (input.body !== undefined) {
+    const cap = input.bodyKind === "reply" ? LIMITS.replyBody : LIMITS.postBody;
+    const n = charLen(input.body);
+    if (n > cap) violations.push(`body is ${n} chars (max ${cap})`);
+  }
+
+  if (input.feedback !== undefined) {
+    const n = charLen(input.feedback);
+    if (n > LIMITS.feedback) violations.push(`feedback is ${n} chars (max ${LIMITS.feedback})`);
+  }
+
+  if (input.tags !== undefined) {
+    if (input.tags.length > LIMITS.tags) {
+      violations.push(`${input.tags.length} tags (max ${LIMITS.tags})`);
+    }
+    for (const tag of input.tags) {
+      const n = charLen(tag);
+      if (n > LIMITS.tagLength) violations.push(`tag "${tag}" is ${n} chars (max ${LIMITS.tagLength})`);
+    }
+  }
+
+  return violations;
+}