@drakulavich/ottoman 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-13
+
+First published release (`@drakulavich/ottoman` on npm).
+
+### Added
+- **SofaClient library** (`src/client.ts`) — typed methods over the SOFA REST
+  API, pure (no fs, no env reads), injectable `SessionStore` and `ClientOptions`:
+  - `tags()` — list all tags
+  - `search(query, opts)` — full-text search with `tag`, `type`, `page`, `perPage` filters
+  - `getPost(postId)` — post detail with replies
+  - `myAgents()` — list authenticated agents
+  - `createPost(req)` — create a til, question, or blueprint
+  - `reply(postId, body)` — reply to a post
+  - `vote(postId, value)` — upvote (+1) or downvote (-1), with read-first guard
+  - `verify(postId, outcome, feedback)` — submit a verification, with read-first guard
+  - `myVerifications(postId)` — list own verifications for a post
+  - `MemorySessionStore` (in-process) and `FileSessionStore` (disk-backed) implementations
+  - Automatic session creation and transparent single retry on `401 invalid_session`
+  - `errorDetail()` handles plain string, FastAPI array, and object `{ error, reasons }` shapes
+- **`sofa` CLI** (`src/cli.ts`) — 8 commands:
+  - `search`, `show`, `post`, `reply`, `vote`, `verify`, `whoami`, `status`
+  - `--json` flag for machine-readable output on all commands
+  - `--agent=<id>` flag to select a specific agent
+  - `--body-file=<path>` or stdin for post/reply bodies
+  - `--tags`, `--title`, `--feedback`, `--page`, `--tag`, `--type` flags
+  - Exit codes: `0` success, `1` user error, `2` API/runtime error
+  - Env: `SOFA_BASE_URL`, `SOFA_MODEL_NAME`, `SOFA_AGENT_ID`
+- **Session cache** (`src/session.ts`) — `FileSessionStore` persists the session
+  token to `~/.sofa/session.json` (chmod 600, 30 s expiry skew)
+- **Credentials loader** (`src/credentials.ts`) — reads `~/.sofa/credentials.json`
+  written by SOFA's onboarding; supports `SOFA_BASE_URL` and `SOFA_AGENT_ID` overrides
+- **Format helpers** (`src/format.ts`) — human-readable output for agents, posts, and search results
+- **Spec-drift test** (`tests/spec-drift.test.ts`) — gated on `OTTOMAN_LIVE=1`;
+  checks that the client's paths and methods remain consistent with the live `openapi.json`
+- **CI** (`.github/workflows/ci.yml`) — typecheck + tests on push/PR
+  (ubuntu + macOS matrix); weekly spec-drift check on Mondays
+- **npm publish workflow** (`.github/workflows/npm-publish.yml`) — tag push
+  `vX.Y.Z` → verify tag matches `package.json` version → `bun run check` →
+  idempotent `npm publish --access public` (prereleases land on the `beta`
+  dist-tag). Package metadata: MIT `LICENSE`, `files` allowlist, `repository`
+- **Static shell completions** for bash (`completions/sofa.bash`), zsh
+  (`completions/_sofa`), and fish (`completions/sofa.fish`): command names,
+  per-command flags, and inline enum values; file completion on `--body-file=`;
+  a drift-guard test keeps them in sync with the CLI surface
+- **`OTTOMAN_DEBUG`** env flag for request tracing: any truthy value prints
+  one-line traces to stderr after each HTTP call (falsey: unset, `""`, `"0"`,
+  `"false"`, `"no"`, `"off"`). Traces never include the API key or session id.
+  `debugEnabled` is exported from the library index
+
+### Fixed
+- `errorDetail()` correctly handles the `{ error: string; reasons?: string[] }` object
+  shape returned by SOFA's content-screening 422 responses (no more `[object Object]`)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Yakutovich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# ottoman
+
+The footrest that pairs with a SOFA. A Bun-native **library + CLI client** for
+[Stack Overflow for Agents](https://agents.stackoverflow.com) — typed methods
+over the REST API, and a `sofa` shell command for humans and agents.
+
+Zero runtime dependencies. Hand-written client, spec-checked against the live
+`openapi.json` in CI.
+
+## Install
+
+```bash
+bun install
+bun link          # exposes the `sofa` command globally
+```
+
+Requires Bun ≥ 1.3.13 and a SOFA API key in `~/.sofa/credentials.json`
+(created by SOFA's agent-directed onboarding).
+
+### Shell completions
+
+Tab completion is available for bash, zsh, and fish. The scripts live in
+`completions/`.
+
+**bash** — add to `~/.bashrc`:
+
+```bash
+source /path/to/ottoman/completions/sofa.bash
+```
+
+**zsh** — either add the directory to `$fpath` before `compinit` in `~/.zshrc`:
+
+```zsh
+fpath=(/path/to/ottoman/completions $fpath)
+autoload -Uz compinit && compinit
+```
+
+or copy the file into any directory already in `$fpath`:
+
+```zsh
+cp completions/_sofa $fpath[1]/_sofa
+```
+
+(The file is named `_sofa` because `compinit` only autoloads completion files
+whose names start with `_`.)
+
+**fish** — copy to fish's completions directory:
+
+```fish
+cp completions/sofa.fish ~/.config/fish/completions/sofa.fish
+```
+
+## CLI
+
+```bash
+sofa search <query> [--tag=x] [--type=til|question|blueprint] [--page=N]
+sofa show <post-id>
+sofa post <til|question|blueprint> --title="..." [--tags=a,b] [--body-file=f]
+sofa reply <post-id> [--body-file=f]
+sofa vote <post-id> <up|down>
+sofa verify <post-id> <worked|changed|failed> --feedback="..."
+sofa whoami
+sofa status
+```
+
+Global flags: `--json`, `--agent=<id>`. Env: `SOFA_BASE_URL`, `SOFA_MODEL_NAME`,
+`SOFA_AGENT_ID`. Post/reply bodies can be piped via stdin.
+
+Exit codes: `0` success, `1` user error, `2` API/runtime error.
+
+## Library
+
+```ts
+import { SofaClient, loadCredentials } from "@drakulavich/ottoman";
+
+const creds = await loadCredentials();
+const client = new SofaClient({ ...creds, clientName: "my-tool", modelName: "unknown" });
+const results = await client.search("bun socket backpressure");
+```
+
+## Debugging
+
+Set `OTTOMAN_DEBUG=1` (or any truthy value) to print one-line request traces to
+stderr:
+
+```
+[debug +12ms] POST /api/sessions → 201 (8ms)
+[debug +21ms] GET /api/tags → 200 (6ms)
+```
+
+Falsey values that disable tracing: unset, `""`, `"0"`, `"false"`, `"no"`,
+`"off"` (case-insensitive). The trace never includes your API key or session id.
+
+## Development
+
+Spec-driven via [OpenSpec](https://github.com/Fission-AI/OpenSpec); design doc
+in `docs/`. TDD; tests run against a fake SOFA server (`Bun.serve`), no
+network. `OTTOMAN_LIVE=1 bun test` adds the spec-drift check against the live
+API.

package/completions/_sofa

@@ -0,0 +1,94 @@
+#compdef sofa
+# zsh completion for sofa
+# Usage:
+#   Option A — add this directory to fpath (in ~/.zshrc before compinit):
+#     fpath=(/path/to/ottoman/completions $fpath)
+#   Option B — copy into any directory already in $fpath:
+#     cp completions/_sofa $fpath[1]/_sofa
+
+local -a commands
+commands=(
+    'search:search posts by keyword'
+    'show:show a post by ID'
+    'post:create a new post'
+    'reply:reply to a post'
+    'vote:upvote or downvote a post'
+    'verify:submit a verification for a post'
+    'whoami:list authenticated agents'
+    'status:check API connectivity and credentials'
+)
+
+local -a global_opts
+global_opts=(
+    '--json[output raw JSON]'
+    '--agent=[use a specific agent ID]:agent id'
+)
+
+_sofa_search() {
+    _arguments \
+        ':query:' \
+        '--tag=[filter by tag]:tag' \
+        '--type=[filter by content type]:type:(til question blueprint)' \
+        '--page=[page number (1-based)]:page number' \
+        $global_opts
+}
+
+_sofa_show() {
+    _arguments \
+        ':post id:' \
+        $global_opts
+}
+
+_sofa_post() {
+    _arguments \
+        ':content type:(til question blueprint)' \
+        '--title=[post title]:title' \
+        '--tags=[comma-separated tags]:tags' \
+        '--body-file=[path to markdown body file]:body file:_files' \
+        $global_opts
+}
+
+_sofa_reply() {
+    _arguments \
+        ':post id:' \
+        '--body-file=[path to markdown body file]:body file:_files' \
+        $global_opts
+}
+
+_sofa_vote() {
+    _arguments \
+        ':post id:' \
+        ':direction:(up down)' \
+        $global_opts
+}
+
+_sofa_verify() {
+    _arguments \
+        ':post id:' \
+        ':outcome:(worked changed failed)' \
+        '--feedback=[verification feedback (<=500 chars)]:feedback' \
+        $global_opts
+}
+
+local state
+_arguments \
+    '1:command:->command' \
+    '*:: :->args' \
+&& return 0
+
+case $state in
+    command)
+        _describe 'sofa command' commands
+        ;;
+    args)
+        case ${words[1]} in
+            search)  _sofa_search  ;;
+            show)    _sofa_show    ;;
+            post)    _sofa_post    ;;
+            reply)   _sofa_reply   ;;
+            vote)    _sofa_vote    ;;
+            verify)  _sofa_verify  ;;
+            whoami|status) _arguments $global_opts ;;
+        esac
+        ;;
+esac

package/completions/sofa.bash

@@ -0,0 +1,116 @@
+# bash completion for sofa
+# Source in ~/.bashrc:  source /path/to/completions/sofa.bash
+# Source of truth for commands/flags: src/cli.ts (USAGE + the dispatch switch).
+# tests/completions.test.ts asserts the command list stays in sync.
+
+_sofa() {
+    local cur prev words cword
+    # -n = keeps `--flag=value` as one word: bash's COMP_WORDBREAKS contains =,
+    # which would otherwise split the token and break every --flag=* pattern below.
+    if type _init_completion >/dev/null 2>&1; then
+        _init_completion -n = || return
+    else
+        # Manual fallback (bash-completion not installed): reassemble cur
+        # across the = split so --flag=* patterns still match.
+        COMPREPLY=()
+        words=("${COMP_WORDS[@]}")
+        cword=$COMP_CWORD
+        cur="${COMP_WORDS[COMP_CWORD]}"
+        prev="${COMP_WORDS[COMP_CWORD-1]}"
+        if [[ "$cur" == "=" && "$prev" == --* ]]; then
+            cur="$prev="
+        elif [[ "$prev" == "=" && "${COMP_WORDS[COMP_CWORD-2]}" == --* ]]; then
+            cur="${COMP_WORDS[COMP_CWORD-2]}=$cur"
+        fi
+    fi
+
+    local commands="search show post reply vote verify whoami status"
+
+    # First positional after 'sofa' — complete command names
+    if [[ $cword -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+        return 0
+    fi
+
+    local command="${words[1]}"
+
+    case "$command" in
+        search)
+            case "$cur" in
+                --type=*)
+                    COMPREPLY=( $(compgen -W "--type=til --type=question --type=blueprint" -- "$cur") )
+                    ;;
+                --*)
+                    COMPREPLY=( $(compgen -W "--tag= --type= --page= --json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+        post)
+            # Second positional (index 2) — content type enum
+            if [[ $cword -eq 2 && ! "$cur" == --* ]]; then
+                COMPREPLY=( $(compgen -W "til question blueprint" -- "$cur") )
+                return 0
+            fi
+            case "$cur" in
+                --body-file=*)
+                    _sofa_body_file
+                    ;;
+                --*)
+                    COMPREPLY=( $(compgen -W "--title= --tags= --body-file= --json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+        reply)
+            case "$cur" in
+                --body-file=*)
+                    _sofa_body_file
+                    ;;
+                --*)
+                    COMPREPLY=( $(compgen -W "--body-file= --json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+        vote)
+            # Third positional (index 3) — direction enum
+            if [[ $cword -eq 3 && ! "$cur" == --* ]]; then
+                COMPREPLY=( $(compgen -W "up down" -- "$cur") )
+                return 0
+            fi
+            case "$cur" in
+                --*)
+                    COMPREPLY=( $(compgen -W "--json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+        verify)
+            # Third positional (index 3) — outcome enum
+            if [[ $cword -eq 3 && ! "$cur" == --* ]]; then
+                COMPREPLY=( $(compgen -W "worked changed failed" -- "$cur") )
+                return 0
+            fi
+            case "$cur" in
+                --*)
+                    COMPREPLY=( $(compgen -W "--feedback= --json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+        show|whoami|status)
+            case "$cur" in
+                --*)
+                    COMPREPLY=( $(compgen -W "--json --agent=" -- "$cur") )
+                    ;;
+            esac
+            ;;
+    esac
+
+    return 0
+}
+
+# Filename completion preserving the --body-file= prefix (used by post and reply).
+_sofa_body_file() {
+    local prefix="${cur#--body-file=}"
+    COMPREPLY=( $(compgen -f -- "$prefix") )
+    COMPREPLY=( "${COMPREPLY[@]/#/--body-file=}" )
+}
+
+complete -F _sofa sofa

package/completions/sofa.fish

@@ -0,0 +1,45 @@
+# fish completion for sofa
+# Copy to ~/.config/fish/completions/sofa.fish
+
+# Disable file completion by default
+complete -c sofa -f
+
+# ── Commands ────────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_use_subcommand' -a 'search'  -d 'Search posts by keyword'
+complete -c sofa -n '__fish_use_subcommand' -a 'show'    -d 'Show a post by ID'
+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 'whoami'  -d 'List authenticated agents'
+complete -c sofa -n '__fish_use_subcommand' -a 'status'  -d 'Check API connectivity and credentials'
+
+# ── Global flags (after a subcommand) ───────────────────────────────────────
+complete -c sofa -n 'not __fish_use_subcommand' -l json       -d 'Output raw JSON'
+complete -c sofa -n 'not __fish_use_subcommand' -l agent -r   -d 'Use a specific agent ID'
+
+# ── search ───────────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_seen_subcommand_from search' -l tag  -r -d 'Filter by tag'
+complete -c sofa -n '__fish_seen_subcommand_from search' -l type -r -a 'til question blueprint' -d 'Filter by content type'
+complete -c sofa -n '__fish_seen_subcommand_from search' -l page -r -d 'Page number (1-based)'
+
+# ── post ─────────────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_seen_subcommand_from post' -a 'til'       -d 'Today I Learned'
+complete -c sofa -n '__fish_seen_subcommand_from post' -a 'question'  -d 'Question'
+complete -c sofa -n '__fish_seen_subcommand_from post' -a 'blueprint' -d 'Blueprint'
+complete -c sofa -n '__fish_seen_subcommand_from post' -l title     -r -d 'Post title'
+complete -c sofa -n '__fish_seen_subcommand_from post' -l tags      -r -d 'Comma-separated tags'
+complete -c sofa -n '__fish_seen_subcommand_from post' -l body-file -r -F -d 'Path to markdown body file'
+
+# ── reply ────────────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_seen_subcommand_from reply' -l body-file -r -F -d 'Path to markdown body file'
+
+# ── vote ─────────────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_seen_subcommand_from vote' -a 'up'   -d 'Upvote'
+complete -c sofa -n '__fish_seen_subcommand_from vote' -a 'down' -d 'Downvote'
+
+# ── verify ───────────────────────────────────────────────────────────────────
+complete -c sofa -n '__fish_seen_subcommand_from verify' -a 'worked'  -d 'Worked as written'
+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)'

package/index.ts

@@ -0,0 +1,30 @@
+export {
+  SofaClient,
+  SofaApiError,
+  MemorySessionStore,
+  type SofaConfig,
+  type Session,
+  type SessionStore,
+  type ContentType,
+  type Tag,
+  type TagList,
+  type PostSummary,
+  type PostList,
+  type PostDetail,
+  type Reply,
+  type PostCreated,
+  type Agent,
+  type AgentStats,
+  type AgentList,
+  type SearchOptions,
+  type PostCreateRequest,
+  type Vote,
+  type VerificationOutcome,
+  type Verification,
+  type VerificationList,
+  type ClientOptions,
+} from "./src/client";
+export { FileSessionStore } from "./src/session";
+export { loadCredentials, CredentialsError, type ResolvedCredentials } from "./src/credentials";
+export { formatSearch, formatPost, formatAgent } from "./src/format";
+export { debugEnabled } from "./src/debug";

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@drakulavich/ottoman",
+  "version": "0.1.0",
+  "description": "Bun-native library + CLI client for Stack Overflow for Agents (SOFA)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drakulavich/ottoman.git"
+  },
+  "type": "module",
+  "module": "index.ts",
+  "bin": {
+    "sofa": "src/cli.ts"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "completions/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "check": "bun run typecheck && bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5"
+  },
+  "engines": {
+    "bun": ">=1.3.13"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env bun
+// sofa — CLI for Stack Overflow for Agents.
+// Exit codes: 0 success, 1 user error, 2 API/runtime error.
+import {
+  SofaClient,
+  SofaApiError,
+  type ContentType,
+  type VerificationOutcome,
+} from "./client";
+import { loadCredentials, CredentialsError } from "./credentials";
+import { FileSessionStore } from "./session";
+import { formatAgent, formatPost, formatSearch } from "./format";
+import { makeDebugLogger } from "./debug";
+
+const USAGE = `usage: sofa <command> [args]
+
+  search <query> [--tag=x] [--type=til|question|blueprint] [--page=N]
+  show <post-id>
+  post <til|question|blueprint> --title="..." [--tags=a,b] [--body-file=f | stdin]
+  reply <post-id> [--body-file=f | stdin]
+  vote <post-id> <up|down>
+  verify <post-id> <worked|changed|failed> --feedback="..."
+  whoami
+  status
+
+global: --json --agent=<id>   env: SOFA_BASE_URL SOFA_MODEL_NAME SOFA_AGENT_ID`;
+
+export interface ParsedArgs {
+  command: string;
+  positionals: string[];
+  flags: Record<string, string | true>;
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const [command = "", ...rest] = argv;
+  const positionals: string[] = [];
+  const flags: Record<string, string | true> = {};
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    if (eq !== -1) {
+      flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+    } else {
+      flags[arg.slice(2)] = true;
+    }
+  }
+  return { command, positionals, flags };
+}
+
+export interface CliDeps {
+  makeClient?: (agentId?: string) => Promise<SofaClient>;
+  readStdin?: () => Promise<string>;
+}
+
+export interface CliResult {
+  exitCode: 0 | 1 | 2;
+  stdout: string;
+  stderr: string;
+}
+
+class UserError extends Error {}
+
+const OUTCOMES: Record<string, VerificationOutcome> = {
+  worked: "worked_as_written",
+  changed: "worked_with_changes",
+  failed: "did_not_work",
+};
+
+const TYPES = new Set(["til", "question", "blueprint"]);
+
+async function defaultMakeClient(agentId?: string): Promise<SofaClient> {
+  const creds = await loadCredentials(agentId);
+  return new SofaClient(
+    {
+      apiKey: creds.apiKey,
+      baseUrl: creds.baseUrl,
+      clientName: "ottoman",
+      modelName: process.env.SOFA_MODEL_NAME ?? "unknown",
+    },
+    new FileSessionStore(),
+    { onDebug: makeDebugLogger(process.env.OTTOMAN_DEBUG) },
+  );
+}
+
+async function readBody(flags: ParsedArgs["flags"], readStdin: () => Promise<string>): Promise<string> {
+  const fromFile = flags["body-file"];
+  if (typeof fromFile === "string") {
+    const f = Bun.file(fromFile);
+    if (!(await f.exists())) throw new UserError(`--body-file: ${fromFile} not found`);
+    return f.text();
+  }
+  const body = (await readStdin()).trim();
+  if (!body) throw new UserError("no body: pipe markdown on stdin or pass --body-file=<path>");
+  return body;
+}
+
+export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliResult> {
+  const makeClient = deps.makeClient ?? defaultMakeClient;
+  const readStdin = deps.readStdin ?? (() => Bun.stdin.text());
+  const { command, positionals, flags } = parseArgs(argv);
+  const json = flags.json === true;
+  const agentId = typeof flags.agent === "string" ? flags.agent : undefined;
+  const emit = (data: unknown, text: string): string => (json ? JSON.stringify(data, null, 2) : text);
+
+  try {
+    switch (command) {
+      case "search": {
+        const [query] = positionals;
+        if (!query) throw new UserError("usage: sofa search <query>");
+        let page: number | undefined;
+        if (typeof flags.page === "string") {
+          page = Number(flags.page);
+          if (!Number.isInteger(page) || page < 1) throw new UserError("--page must be a positive integer");
+        }
+        let type: ContentType | undefined;
+        if (typeof flags.type === "string") {
+          if (!TYPES.has(flags.type)) throw new UserError("--type must be til, question, or blueprint");
+          type = flags.type as ContentType;
+        }
+        const client = await makeClient(agentId);
+        const result = await client.search(query, {
+          tag: typeof flags.tag === "string" ? flags.tag : undefined,
+          type,
+          page,
+        });
+        return { exitCode: 0, stdout: emit(result, formatSearch(result)), stderr: "" };
+      }
+      case "show": {
+        const [postId] = positionals;
+        if (!postId) throw new UserError("usage: sofa show <post-id>");
+        const client = await makeClient(agentId);
+        const post = await client.getPost(postId);
+        return { exitCode: 0, stdout: emit(post, formatPost(post)), stderr: "" };
+      }
+      case "post": {
+        const [type] = positionals;
+        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 client = await makeClient(agentId);
+        const post = await client.createPost({ content_type: type as ContentType, title: flags.title, body, tags });
+        return { exitCode: 0, stdout: emit(post, `created ${post.content_type} ${post.id}`), stderr: "" };
+      }
+      case "reply": {
+        const [postId] = positionals;
+        if (!postId) throw new UserError("usage: sofa reply <post-id>");
+        const body = await readBody(flags, readStdin);
+        const client = await makeClient(agentId);
+        const reply = await client.reply(postId, body);
+        return { exitCode: 0, stdout: emit(reply, `created reply ${reply.id} on ${reply.parent_id}`), stderr: "" };
+      }
+      case "vote": {
+        const [postId, direction] = positionals;
+        if (!postId || !["up", "down"].includes(direction ?? "")) {
+          throw new UserError("usage: sofa vote <post-id> <up|down>");
+        }
+        const client = await makeClient(agentId);
+        const vote = await client.vote(postId, direction === "up" ? 1 : -1);
+        return { exitCode: 0, stdout: emit(vote, `voted ${direction} on ${vote.post_id}`), stderr: "" };
+      }
+      case "verify": {
+        const [postId, outcomeKey] = positionals;
+        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 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 "whoami": {
+        const client = await makeClient(agentId);
+        const agents = await client.myAgents();
+        const text = agents.items.map(formatAgent).join("\n\n");
+        return { exitCode: 0, stdout: emit(agents, text), stderr: "" };
+      }
+      case "status": {
+        const client = await makeClient(agentId); // throws CredentialsError -> exit 1
+        const agents = await client.myAgents(); // exercises session + identity
+        const status = { ready: true, agents: agents.items.length };
+        return { exitCode: 0, stdout: emit(status, `SOFA status: ready (key present, session ok, ${agents.items.length} agent(s))`), stderr: "" };
+      }
+      default:
+        throw new UserError(USAGE);
+    }
+  } catch (err) {
+    if (err instanceof UserError || err instanceof CredentialsError) {
+      return { exitCode: 1, stdout: "", stderr: err.message };
+    }
+    if (err instanceof SofaApiError) {
+      return { exitCode: 2, stdout: "", stderr: `SOFA API error (${err.status}): ${err.message}` };
+    }
+    return { exitCode: 2, stdout: "", stderr: String(err) };
+  }
+}
+
+if (import.meta.main) {
+  const result = await runCli(process.argv.slice(2));
+  if (result.stdout) console.log(result.stdout);
+  if (result.stderr) console.error(result.stderr);
+  process.exit(result.exitCode);
+}

package/src/client.ts

@@ -0,0 +1,329 @@
+// Pure SOFA API client: fetch only, no fs, no env reads.
+// Session persistence is delegated to a SessionStore so the CLI can plug in
+// the disk-backed store (src/session.ts) while the library default stays pure.
+
+export interface SofaConfig {
+  apiKey: string;
+  baseUrl: string;
+  clientName: string;
+  modelName: string;
+}
+
+export interface Session {
+  session_id: string;
+  expires_at: string;
+}
+
+export interface SessionStore {
+  load(): Promise<Session | null>;
+  save(session: Session): Promise<void>;
+  clear(): Promise<void>;
+}
+
+export class MemorySessionStore implements SessionStore {
+  private session: Session | null = null;
+  async load() {
+    return this.session;
+  }
+  async save(session: Session) {
+    this.session = session;
+  }
+  async clear() {
+    this.session = null;
+  }
+}
+
+export class SofaApiError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "SofaApiError";
+  }
+}
+
+export interface Tag {
+  id: string;
+  name: string;
+  description: string;
+}
+
+export interface TagList {
+  tags: Tag[];
+}
+
+export type ContentType = "question" | "til" | "blueprint";
+
+export interface PostSummary {
+  id: string;
+  title: string;
+  content_type: ContentType;
+  agent_id: string;
+  agent_name: string;
+  agent_is_top_contributor: boolean;
+  tags: Tag[] | null;
+  vote_count?: number;
+  reply_count: number;
+  view_count: number;
+  body_excerpt: string;
+  trust_summary: unknown;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface PostList {
+  items: PostSummary[];
+  total: number;
+  page: number;
+  per_page: number;
+  has_next: boolean;
+}
+
+export interface Reply {
+  id: string;
+  parent_id: string;
+  body: string;
+  agent_id: string;
+  agent_name: string;
+  agent_is_top_contributor: boolean;
+  vote_count?: number;
+  trust_summary: unknown;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface PostDetail extends Omit<PostSummary, "body_excerpt"> {
+  body: string;
+  replies: Reply[];
+}
+
+export interface AgentStats {
+  question_count: number;
+  answer_count: number;
+  blueprint_count: number;
+  til_count: number;
+  vote_count: number;
+  verification_count: number;
+  reputation: number;
+}
+
+export interface Agent {
+  id: string;
+  name: string;
+  description: string;
+  persona: string;
+  avatar_type: string;
+  agent_is_top_contributor: boolean;
+  created_at: string;
+  stats: AgentStats;
+}
+
+export interface AgentList {
+  items: Agent[];
+}
+
+export interface SearchOptions {
+  tag?: string;
+  type?: ContentType;
+  page?: number;
+  perPage?: number;
+}
+
+async function errorDetail(res: Response): Promise<string> {
+  try {
+    const data = (await res.json()) as { error?: unknown; detail?: unknown };
+    if (Array.isArray(data.detail)) {
+      const joined = (data.detail as Array<{ msg?: string }>).map((d) => d.msg ?? JSON.stringify(d)).join("; ");
+      return joined || res.statusText;
+    }
+    if (data.detail !== null && typeof data.detail === "object") {
+      const obj = data.detail as { error?: string; reasons?: string[] };
+      if (typeof obj.error === "string") {
+        const reasons = Array.isArray(obj.reasons) && obj.reasons.length > 0 ? ` (${obj.reasons.join("; ")})` : "";
+        return obj.error + reasons;
+      }
+      return JSON.stringify(data.detail);
+    }
+    if (typeof data.error === "string") return data.error;
+    if (data.error !== undefined) return JSON.stringify(data.error);
+    if (typeof data.detail === "string") return data.detail;
+    return res.statusText;
+  } catch {
+    return res.statusText;
+  }
+}
+
+export interface PostCreateRequest {
+  content_type: ContentType;
+  title: string;
+  body: string;
+  tags?: string[];
+}
+
+export interface Vote {
+  id: string;
+  post_id: string;
+  agent_id: string;
+  value: number;
+  created_at: string;
+}
+
+export interface PostCreated {
+  id: string;
+  parent_id: string | null;
+  content_type: ContentType;
+  title: string;
+  body: string;
+  tags: Tag[] | null;
+  reply_count: number;
+  view_count: number;
+  vote_count?: number;
+  agent_id: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export type VerificationOutcome = "worked_as_written" | "worked_with_changes" | "did_not_work";
+
+export interface Verification {
+  id: string;
+  post_id: string;
+  agent_id: string;
+  outcome: VerificationOutcome;
+  feedback: string;
+  created_at: string;
+}
+
+export interface VerificationList {
+  verifications: Verification[];
+}
+
+export interface ClientOptions {
+  /** Delay before the single retry on a read-first rejection (used by vote() and verify()). */
+  readFirstRetryDelayMs?: number;
+  /** Called after each HTTP response with a one-line trace. Never receives secrets. */
+  onDebug?: (line: string) => void;
+}
+
+export class SofaClient {
+  constructor(
+    private readonly config: SofaConfig,
+    private readonly store: SessionStore = new MemorySessionStore(),
+    private readonly options: ClientOptions = {},
+  ) {}
+
+  private async tracedFetch(method: string, path: string, init: RequestInit): Promise<Response> {
+    const url = `${this.config.baseUrl}${path}`;
+    const { onDebug } = this.options;
+    if (!onDebug) return fetch(url, init);
+    const t0 = performance.now();
+    const res = await fetch(url, init);
+    onDebug(`${method} ${path} → ${res.status} (${Math.round(performance.now() - t0)}ms)`);
+    return res;
+  }
+
+  private async createSession(): Promise<Session> {
+    const res = await this.tracedFetch("POST", "/api/sessions", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`,
+        "X-Sofa-Client-Name": this.config.clientName,
+        "X-Sofa-Model-Name": this.config.modelName,
+        "Content-Type": "application/json",
+      },
+      body: "{}",
+    });
+    if (!res.ok) throw new SofaApiError(res.status, await errorDetail(res));
+    const session = (await res.json()) as Session;
+    await this.store.save(session);
+    return session;
+  }
+
+  protected async request<T>(method: string, path: string, body?: unknown, retried = false): Promise<T> {
+    // Not concurrency-safe by design: two concurrent calls on a fresh client may both create sessions (harmless for one-shot CLI use; no in-flight dedup).
+    const session = (await this.store.load()) ?? (await this.createSession());
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.config.apiKey}`,
+      "X-Sofa-Session": session.session_id,
+    };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    const res = await this.tracedFetch(method, path, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (res.status === 401 && !retried) {
+      this.options.onDebug?.("session invalid — recreating");
+      await this.store.clear();
+      return this.request<T>(method, path, body, true);
+    }
+    if (!res.ok) throw new SofaApiError(res.status, await errorDetail(res));
+    return (await res.json()) as T;
+  }
+
+  async tags(): Promise<TagList> {
+    return this.request<TagList>("GET", "/api/tags");
+  }
+
+  async search(query: string, opts: SearchOptions = {}): Promise<PostList> {
+    const params = new URLSearchParams({ search: query });
+    if (opts.tag) params.set("tag", opts.tag);
+    if (opts.type) params.set("content_type", opts.type);
+    if (opts.page !== undefined) params.set("page", String(opts.page));
+    if (opts.perPage !== undefined) params.set("per_page", String(opts.perPage));
+    return this.request<PostList>("GET", `/api/posts?${params}`);
+  }
+
+  async getPost(postId: string): Promise<PostDetail> {
+    return this.request<PostDetail>("GET", `/api/posts/${encodeURIComponent(postId)}`);
+  }
+
+  async myAgents(): Promise<AgentList> {
+    return this.request<AgentList>("GET", "/api/me/agents");
+  }
+
+  async createPost(req: PostCreateRequest): Promise<PostCreated> {
+    return this.request<PostCreated>("POST", "/api/posts", req);
+  }
+
+  async reply(postId: string, body: string): Promise<PostCreated> {
+    return this.request<PostCreated>("POST", `/api/posts/${encodeURIComponent(postId)}/replies`, { body });
+  }
+
+  // SOFA's read-first guard rejects writes on posts this agent hasn't read; the
+  // guard's projection is eventually consistent, so one delayed retry on a
+  // non-auth 4xx. Used by vote() and verify().
+  private async readFirstWrite<T>(postId: string, fn: () => Promise<T>): Promise<T> {
+    await this.getPost(postId);
+    try {
+      return await fn();
+    } catch (err) {
+      if (err instanceof SofaApiError && err.status >= 400 && err.status < 500 && err.status !== 401 && err.status !== 403) {
+        await new Promise((r) => setTimeout(r, this.options.readFirstRetryDelayMs ?? 1500));
+        return fn();
+      }
+      throw err;
+    }
+  }
+
+  async vote(postId: string, value: 1 | -1): Promise<Vote> {
+    return this.readFirstWrite(postId, () =>
+      this.request<Vote>("POST", "/api/votes", { post_id: postId, value }),
+    );
+  }
+
+  async verify(postId: string, outcome: VerificationOutcome, feedback: string): Promise<Verification> {
+    if (feedback.length > 500) {
+      throw new SofaApiError(400, `feedback is ${feedback.length} chars; SOFA caps it at 500`);
+    }
+    return this.readFirstWrite(postId, () =>
+      this.request<Verification>("POST", "/api/verifications", { post_id: postId, outcome, feedback }),
+    );
+  }
+
+  async myVerifications(postId: string): Promise<VerificationList> {
+    const params = new URLSearchParams({ post_id: postId });
+    return this.request<VerificationList>("GET", `/api/me/verifications?${params}`);
+  }
+}

package/src/credentials.ts

@@ -0,0 +1,59 @@
+// Loads ~/.sofa/credentials.json (written by SOFA agent-directed onboarding).
+// Shape: { [agent_id]: { agent_name, base_url, api_key, ...metadata } }.
+// HOME is read at call time, never module load — tests redirect it.
+
+export interface StoredCredential {
+  agent_name: string;
+  base_url: string;
+  api_key: string;
+}
+
+export interface ResolvedCredentials {
+  agentId: string;
+  agentName: string;
+  baseUrl: string;
+  apiKey: string;
+}
+
+export class CredentialsError extends Error {}
+
+function credentialsPath(): string {
+  return `${process.env.HOME}/.sofa/credentials.json`;
+}
+
+export async function loadCredentials(agentId?: string): Promise<ResolvedCredentials> {
+  const file = Bun.file(credentialsPath());
+  let store: Record<string, StoredCredential>;
+  try {
+    store = (await file.json()) as Record<string, StoredCredential>;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === "ENOENT") {
+      throw new CredentialsError(
+        "no SOFA credentials at ~/.sofa/credentials.json — complete SOFA agent onboarding first (GET https://agents.stackoverflow.com/api/onboarding)",
+      );
+    }
+    throw new CredentialsError(
+      "~/.sofa/credentials.json is not valid JSON — fix or re-run SOFA onboarding",
+    );
+  }
+  const ids = Object.keys(store);
+  if (ids.length === 0) {
+    throw new CredentialsError(
+      "credentials.json contains no agents — complete SOFA agent onboarding first",
+    );
+  }
+  const id = agentId ?? process.env.SOFA_AGENT_ID ?? (ids.length === 1 ? ids[0] : undefined);
+  if (!id) {
+    throw new CredentialsError(`multiple agents in credentials.json — pass --agent=<id> (have: ${ids.join(", ")})`);
+  }
+  const cred = store[id];
+  if (!cred) {
+    throw new CredentialsError(`agent '${id}' not found in credentials.json (have: ${ids.join(", ")})`);
+  }
+  return {
+    agentId: id,
+    agentName: cred.agent_name,
+    baseUrl: process.env.SOFA_BASE_URL ?? cred.base_url,
+    apiKey: cred.api_key,
+  };
+}

package/src/debug.ts

@@ -0,0 +1,20 @@
+// CLI-side debug helpers. Not imported by src/client.ts (which stays pure).
+
+// OTTOMAN_DEBUG env: unset/""/"0"/"false"/"no"/"off" (case-insensitive) → disabled; anything else → enabled.
+const FALSEY = new Set(["", "0", "false", "no", "off"]);
+
+export function debugEnabled(value: string | undefined): boolean {
+  if (value === undefined) return false;
+  return !FALSEY.has(value.toLowerCase());
+}
+
+/** Returns a debug writer prefixed with +Nms since process start, or undefined when disabled. */
+export function makeDebugLogger(
+  envValue: string | undefined,
+  write: (chunk: string) => void = (chunk) => void process.stderr.write(chunk),
+): ((line: string) => void) | undefined {
+  if (!debugEnabled(envValue)) return undefined;
+  return (line: string) => {
+    write(`[debug +${Math.round(performance.now())}ms] ${line}\n`);
+  };
+}

package/src/format.ts

@@ -0,0 +1,35 @@
+// Human-readable rendering. --json bypasses this module entirely.
+import type { Agent, PostDetail, PostList } from "./client";
+
+const votes = (n?: number): string => (n !== undefined ? `▲${n} ` : "");
+
+export function formatSearch(list: PostList): string {
+  if (list.items.length === 0) return "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})`,
+  );
+  lines.push(`— page ${list.page}, showing ${list.items.length} of ${list.total}${list.has_next ? " (more pages)" : ""}`);
+  return lines.join("\n");
+}
+
+export function formatPost(post: PostDetail): string {
+  const out = [
+    `# ${post.title}`,
+    `${post.id}  [${post.content_type}] by ${post.agent_name}  ${votes(post.vote_count)}tags: ${(post.tags ?? []).map((t) => t.name).join(", ")}`,
+    "",
+    post.body,
+  ];
+  for (const r of post.replies) {
+    out.push("", `--- reply ${r.id} by ${r.agent_name} (${votes(r.vote_count)})---`, r.body);
+  }
+  return out.join("\n");
+}
+
+export function formatAgent(agent: Agent): string {
+  const s = agent.stats;
+  return [
+    `${agent.name} (${agent.id})`,
+    agent.description,
+    `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");
+}

package/src/session.ts

@@ -0,0 +1,37 @@
+// Disk-backed session cache: ~/.sofa/session.json.
+// One-shot CLI invocations must not pay a session-create round trip per call.
+// HOME resolved at call time (tests redirect it). A session expiring within
+// 30s is treated as absent so we never race the server-side expiry.
+import { chmod, rm } from "node:fs/promises";
+import type { Session, SessionStore } from "./client";
+
+const EXPIRY_SKEW_MS = 30_000;
+
+function sessionPath(): string {
+  return `${process.env.HOME}/.sofa/session.json`;
+}
+
+export class FileSessionStore implements SessionStore {
+  async load(): Promise<Session | null> {
+    const file = Bun.file(sessionPath());
+    if (!(await file.exists())) return null;
+    try {
+      const session = (await file.json()) as Session;
+      if (!session.session_id || !session.expires_at) return null;
+      if (new Date(session.expires_at).getTime() - Date.now() < EXPIRY_SKEW_MS) return null;
+      return session;
+    } catch {
+      return null;
+    }
+  }
+
+  async save(session: Session): Promise<void> {
+    const path = sessionPath();
+    await Bun.write(path, JSON.stringify(session));
+    await chmod(path, 0o600);
+  }
+
+  async clear(): Promise<void> {
+    await rm(sessionPath(), { force: true });
+  }
+}