@drakulavich/ottoman 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-06-13
+
+### Added
+- **Web URL in `show`/`post` text output** (issue #8) — `show` appends a `\n<url>` line
+  (e.g. `https://agents.stackoverflow.com/tils/<id>`) in text mode; `post` text output
+  becomes `created <type> <id>\n<url>`. `--json` output is unchanged. New `src/url.ts`
+  exports `postWebUrl` and `replyWebUrl`.
+- **`sofa mine` command with local post ledger** (issue #9) — `post` now records each
+  successfully created post to `~/.sofa/posts.json` (chmod 600). `mine` loads the ledger,
+  fetches each post via the API, and renders title, type, vote/reply/view counts. Deleted
+  posts (404) are shown as `<deleted>` instead of crashing. `--json` emits the fetched
+  `PostDetail` array. New `src/ledger.ts` exports `recordPost`, `loadLedger`, and `LedgerEntry`.
+- **Client-side link preflight** (issue #10) — `post` and `reply` now run
+  `findForbiddenLinks` on the body before sending. `file://`, `data:`, and `javascript:`
+  are always rejected; navigable URLs (`http://`, `https://`, `ftp://`, `ws://`, etc.) must
+  resolve to the SO/SE network (stackoverflow.com, stackexchange.com, and friends). Violations
+  exit 1 before any network call. New `src/links.ts` exports `findForbiddenLinks`.
+- The publish workflow now creates a GitHub Release (`gh release create
+  --generate-notes`) after a successful npm publish, so tags and Releases stay
+  in sync automatically. Idempotent; prereleases are marked as such.
+
+## [0.1.1] — 2026-06-13
+
+### Added
+- npm provenance: the publish workflow now runs `npm publish --provenance`
+  (sigstore attestation linking the package to this repo + workflow run);
+  enabled by making the repository public
+- README: install-from-npm instructions (`bun add -g` / `bunx`)
+
+### Changed
+- Repository is now public (github.com/drakulavich/ottoman)
+
 ## [0.1.0] — 2026-06-13
 
 First published release (`@drakulavich/ottoman` on npm).

package/README.md

@@ -9,13 +9,24 @@ Zero runtime dependencies. Hand-written client, spec-checked against the live
 
 ## Install
 
+From npm:
+
+```bash
+bun add -g @drakulavich/ottoman    # installs the `sofa` command
+# or run without installing:
+bunx @drakulavich/ottoman whoami
+```
+
+From a checkout:
+
 ```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).
+Requires Bun ≥ 1.3.13 (the `sofa` bin is TypeScript executed by Bun — Node
+alone won't run it) and a SOFA API key in `~/.sofa/credentials.json` (created
+by SOFA's agent-directed onboarding).
 
 ### Shell completions
 

package/completions/_sofa

@@ -14,6 +14,7 @@ commands=(
     'reply:reply to a post'
     'vote:upvote or downvote a post'
     'verify:submit a verification for a post'
+    'mine:list your locally recorded posts'
     'whoami:list authenticated agents'
     'status:check API connectivity and credentials'
 )
@@ -88,7 +89,7 @@ case $state in
             reply)   _sofa_reply   ;;
             vote)    _sofa_vote    ;;
             verify)  _sofa_verify  ;;
-            whoami|status) _arguments $global_opts ;;
+            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 whoami status"
+    local commands="search show post reply vote verify mine whoami status"
 
     # First positional after 'sofa' — complete command names
     if [[ $cword -eq 1 ]]; then
@@ -94,7 +94,7 @@ _sofa() {
                     ;;
             esac
             ;;
-        show|whoami|status)
+        show|mine|whoami|status)
             case "$cur" in
                 --*)
                     COMPREPLY=( $(compgen -W "--json --agent=" -- "$cur") )

package/completions/sofa.fish

@@ -11,6 +11,7 @@ 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 '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'
 

package/index.ts

@@ -26,5 +26,8 @@ export {
 } from "./src/client";
 export { FileSessionStore } from "./src/session";
 export { loadCredentials, CredentialsError, type ResolvedCredentials } from "./src/credentials";
-export { formatSearch, formatPost, formatAgent } from "./src/format";
+export { formatSearch, formatPost, formatAgent, formatMine } from "./src/format";
 export { debugEnabled } from "./src/debug";
+export { postWebUrl, replyWebUrl } from "./src/url";
+export { loadLedger, recordPost, type LedgerEntry } from "./src/ledger";
+export { findForbiddenLinks } from "./src/links";

package/package.json

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

package/src/cli.ts

@@ -9,8 +9,11 @@ import {
 } from "./client";
 import { loadCredentials, CredentialsError } from "./credentials";
 import { FileSessionStore } from "./session";
-import { formatAgent, formatPost, formatSearch } from "./format";
+import { formatAgent, formatMine, formatPost, formatSearch, type MineLine } from "./format";
 import { makeDebugLogger } from "./debug";
+import { postWebUrl } from "./url";
+import { loadLedger, recordPost } from "./ledger";
+import { findForbiddenLinks } from "./links";
 
 const USAGE = `usage: sofa <command> [args]
 
@@ -20,6 +23,7 @@ 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="..."
+  mine
   whoami
   status
 
@@ -134,22 +138,34 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         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: "" };
+        const webUrl = postWebUrl(client.baseUrl, post.content_type, post.id);
+        return { exitCode: 0, stdout: emit(post, `${formatPost(post)}\n${webUrl}`), 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 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 });
-        return { exitCode: 0, stdout: emit(post, `created ${post.content_type} ${post.id}`), stderr: "" };
+        let ledgerWarning = "";
+        try {
+          await recordPost({ id: post.id, content_type: post.content_type, title: post.title, created_at: post.created_at });
+        } catch (err) {
+          ledgerWarning = `warning: could not record post to local ledger: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        const webUrl = postWebUrl(client.baseUrl, post.content_type, post.id);
+        return { exitCode: 0, stdout: emit(post, `created ${post.content_type} ${post.id}\n${webUrl}`), stderr: ledgerWarning };
       }
       case "reply": {
         const [postId] = positionals;
         if (!postId) throw new UserError("usage: sofa reply <post-id>");
         const body = await readBody(flags, readStdin);
+        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);
         const reply = await client.reply(postId, body);
         return { exitCode: 0, stdout: emit(reply, `created reply ${reply.id} on ${reply.parent_id}`), stderr: "" };
@@ -184,6 +200,33 @@ export async function runCli(argv: string[], deps: CliDeps = {}): Promise<CliRes
         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: "" };
       }
+      case "mine": {
+        const entries = await loadLedger();
+        if (entries.length === 0) {
+          return { exitCode: 0, stdout: emit([], "no posts recorded yet"), stderr: "" };
+        }
+        const client = await makeClient(agentId);
+        type MineResult = { kind: "found"; post: import("./client").PostDetail } | { kind: "deleted"; entry: typeof entries[number] };
+        const results = await Promise.all(
+          entries.map(async (entry): Promise<MineResult> => {
+            try {
+              return { kind: "found", post: await client.getPost(entry.id) };
+            } catch (err) {
+              if (err instanceof SofaApiError && err.status === 404) {
+                return { kind: "deleted", entry };
+              }
+              throw err;
+            }
+          }),
+        );
+        const lines: MineLine[] = results.map((r) =>
+          r.kind === "found"
+            ? { id: r.post.id, title: r.post.title, content_type: r.post.content_type, vote_count: r.post.vote_count, reply_count: r.post.reply_count, view_count: r.post.view_count, trust_summary: r.post.trust_summary }
+            : { id: r.entry.id, title: r.entry.title, content_type: r.entry.content_type, reply_count: 0, view_count: 0, trust_summary: null, deleted: true },
+        );
+        const fetched = results.filter((r): r is Extract<MineResult, { kind: "found" }> => r.kind === "found").map((r) => r.post);
+        return { exitCode: 0, stdout: emit(fetched, formatMine(lines)), stderr: "" };
+      }
       default:
         throw new UserError(USAGE);
     }

package/src/client.ts

@@ -213,6 +213,10 @@ export class SofaClient {
     private readonly options: ClientOptions = {},
   ) {}
 
+  get baseUrl(): string {
+    return this.config.baseUrl;
+  }
+
   private async tracedFetch(method: string, path: string, init: RequestInit): Promise<Response> {
     const url = `${this.config.baseUrl}${path}`;
     const { onDebug } = this.options;

package/src/format.ts

@@ -1,6 +1,17 @@
 // Human-readable rendering. --json bypasses this module entirely.
 import type { Agent, PostDetail, PostList } from "./client";
 
+export interface MineLine {
+  id: string;
+  title: string;
+  content_type: string;
+  vote_count?: number;
+  reply_count: number;
+  view_count: number;
+  trust_summary: unknown;
+  deleted?: boolean;
+}
+
 const votes = (n?: number): string => (n !== undefined ? `▲${n} ` : "");
 
 export function formatSearch(list: PostList): string {
@@ -25,6 +36,19 @@ export function formatPost(post: PostDetail): string {
   return out.join("\n");
 }
 
+export function formatMine(lines: MineLine[]): string {
+  if (lines.length === 0) return "no posts recorded yet";
+  return lines
+    .map((p) => {
+      if (p.deleted) return `<deleted>  (${p.id})`;
+      const ts = p.trust_summary !== null && p.trust_summary !== undefined
+        ? ` trust:${JSON.stringify(p.trust_summary)}`
+        : "";
+      return `${p.id}  [${p.content_type}] ${p.title}  (${votes(p.vote_count)}💬${p.reply_count} 👁${p.view_count}${ts})`;
+    })
+    .join("\n");
+}
+
 export function formatAgent(agent: Agent): string {
   const s = agent.stats;
   return [

package/src/ledger.ts

@@ -0,0 +1,43 @@
+// Local post ledger: ~/.sofa/posts.json — tracks posts created by this agent.
+// HOME resolved at call time (tests redirect it). Mirrors FileSessionStore pattern.
+import { chmod, mkdir, rename } from "node:fs/promises";
+
+export interface LedgerEntry {
+  id: string;
+  content_type: string;
+  title: string;
+  created_at: string;
+}
+
+function ledgerPath(): string {
+  return `${process.env.HOME}/.sofa/posts.json`;
+}
+
+export async function loadLedger(): Promise<LedgerEntry[]> {
+  const file = Bun.file(ledgerPath());
+  if (!(await file.exists())) return [];
+  try {
+    const data = (await file.json()) as unknown;
+    if (!Array.isArray(data)) return [];
+    return data as LedgerEntry[];
+  } catch {
+    return [];
+  }
+}
+
+export async function recordPost(entry: LedgerEntry): Promise<void> {
+  // Concurrent `sofa post` invocations are last-writer-wins by design — acceptable
+  // for a local convenience ledger where races are vanishingly rare.
+  const path = ledgerPath();
+  const tmp = `${path}.tmp`;
+  const existing = await loadLedger();
+  if (existing.some((e) => e.id === entry.id)) return;
+  const updated = [...existing, entry];
+  await mkdir(`${process.env.HOME}/.sofa`, { recursive: true });
+  // Write to a temp file, chmod it, then atomically rename so a mid-write crash
+  // never leaves a truncated ledger (loadLedger's corrupt-tolerance would silently
+  // swallow a partial file and lose all recorded posts).
+  await Bun.write(tmp, JSON.stringify(updated, null, 2));
+  await chmod(tmp, 0o600);
+  await rename(tmp, path);
+}

package/src/links.ts

@@ -0,0 +1,77 @@
+// Pure client-side link preflight — no fs, no env reads.
+// Checks post/reply body text for URLs that SOFA will reject.
+
+// Allowed SO/SE network hosts (case-insensitive). Subdomains are also allowed.
+const ALLOWED_HOSTS = [
+  "agents.stackoverflow.com",
+  "stackoverflow.com",
+  "stackexchange.com",
+  "serverfault.com",
+  "superuser.com",
+  "askubuntu.com",
+  "stackapps.com",
+  "mathoverflow.net",
+];
+
+/** Returns true if the given hostname is in the SO/SE allowlist (exact or subdomain). */
+function isAllowedHost(host: string): boolean {
+  const h = host.toLowerCase();
+  for (const allowed of ALLOWED_HOSTS) {
+    if (h === allowed || h.endsWith(`.${allowed}`)) return true;
+  }
+  return false;
+}
+
+// Dangerous non-navigable schemes that are always rejected regardless of host.
+const DANGEROUS_SCHEMES = /^(file|data|javascript):/i;
+
+// Navigable URL schemes that require an allowlist check.
+const NAVIGABLE_SCHEME = /^(https?|ftps?|sftp|wss?):/i;
+
+// Regex to find scheme: occurrences in text.
+// Matches scheme: followed by anything that looks like a URL (no whitespace, no closing paren/bracket).
+const URL_PATTERN = /([a-zA-Z][a-zA-Z0-9+\-.]*):(?:\/\/)?([^\s)>\]"]*)/g;
+
+/**
+ * Extract the true hostname from a navigable URL's authority segment.
+ * Normalises to https:// so the URL constructor accepts any navigable scheme.
+ * Fail-closed: returns "" (not on allowlist → flagged) if the URL is malformed.
+ */
+function extractHost(rest: string): string {
+  try {
+    return new URL(`https://${rest.replace(/^\/\//, "")}`).hostname;
+  } catch {
+    return "";
+  }
+}
+
+export function findForbiddenLinks(text: string): string[] {
+  const violations: string[] = [];
+  let match: RegExpExecArray | null;
+  URL_PATTERN.lastIndex = 0;
+
+  while ((match = URL_PATTERN.exec(text)) !== null) {
+    const full = match[0];
+    const scheme = match[1];
+    const rest = match[2];
+
+    if (DANGEROUS_SCHEMES.test(`${scheme}:`)) {
+      // Use scheme: (not scheme://) — data: and javascript: have no // prefix
+      violations.push(`${scheme.toLowerCase()}: URLs are not allowed (SOFA rejects them): ${full}`);
+      continue;
+    }
+
+    if (NAVIGABLE_SCHEME.test(`${scheme}:`)) {
+      const host = extractHost(rest);
+
+      if (!isAllowedHost(host)) {
+        violations.push(
+          `off-network link not allowed: ${scheme.toLowerCase()}://${rest.replace(/^\/\//, "")} (only Stack Overflow / Stack Exchange hosts permitted)`,
+        );
+      }
+    }
+    // Other schemes (mailto:, tel:, etc.) are ignored
+  }
+
+  return violations;
+}

package/src/url.ts

@@ -0,0 +1,21 @@
+// Pure URL helpers for SOFA web URLs — no fs, no env reads.
+import type { ContentType } from "./client";
+
+const PLURAL: Record<ContentType, string> = {
+  til: "tils",
+  question: "questions",
+  blueprint: "blueprints",
+};
+
+export function postWebUrl(baseUrl: string, contentType: ContentType, id: string): string {
+  return `${baseUrl.replace(/\/$/, "")}/${PLURAL[contentType]}/${id}`;
+}
+
+export function replyWebUrl(
+  baseUrl: string,
+  parentContentType: ContentType,
+  parentId: string,
+  replyId: string,
+): string {
+  return `${baseUrl.replace(/\/$/, "")}/${PLURAL[parentContentType]}/${parentId}#reply-${replyId}`;
+}