postern CLAUDE.md

Postern

Postern is a remote driver for a live Pharo Smalltalk image. It exposes the running image as an HTTP server: clients send Smalltalk to /repl, read live documentation from /help, and drive compile / test / inspect / commit loops without going through the Pharo GUI. Postern was carved out of punt-labs/claude-agent-sdk-smalltalk in early 2026 and ships independently. It has zero Claude dependency by design — agent integration happens at the HTTP boundary, not in the Smalltalk image.

This file covers the contributor workflow for developing Postern. For agents using Postern's runtime (bootstrap, /help flow, /repl usage, eval token handling), read AGENTS.md.

The public-facing description is in README.md. Architecture and engineering conventions live below.

What Postern Is

A single product, three packages plus a baseline:

1. Postern-Core — the HTTP eval server. PosternServer (Zinc-backed) binds to localhost:8422 (or $EVAL_PORT), routes /repl, /health, and /help/*, enforces auth on /repl when configured, and converts LF line endings to CR before passing source to the Pharo compiler.
2. Postern-Dashboard — PosternDashboard Morphic UI showing live request traffic, status, and request/response bodies. Optional; loaded by the default group but never required by Postern-Core.
3. Postern-IcebergExtensions — repairs Iceberg reference-commit drift after CLI git operations. Optional; loaded by the default group.
4. BaselineOfPostern — Metacello baseline declaring all three packages plus their *-Tests siblings. Three groups: default (Core + Dashboard + IcebergExtensions), tests, all.

Loading from another image:

Metacello new
  baseline: 'Postern';
  repository: 'github://punt-labs/postern:main';
  load.

Architecture

• HTTP eval server — PosternServer is Zinc-backed (Pharo's built-in HTTP). Loopback-only by default. startOn: and startOn:withAuth: bind to localhost; startPublicOn: binds to all interfaces and always requires a token. /health and /help are unauthenticated; /repl uses an X-Eval-Token header read from .tmp/eval-token.
• Live /help system — help content is generated from the loaded image, not static markdown. /help/api, /help/browse, /help/pharo, /help/dispatch, /help/lint, /help/git, /help/testing, /help/safety, /help/makefile, /help/lessons. Each section reflects the actual loaded packages; updating the image updates the help.
• Eval pipeline — POST /repl body is text/plain Smalltalk. Server normalises line endings, evaluates in OpalCompiler, returns printString of the result. Errors return the exception's description. No streaming.
• Iceberg sync — Postern-IcebergExtensions adds a repairAfterCli helper for the case where you've committed via CLI (make targets, git directly) and Iceberg's reference commit has drifted.
• Dashboard — Morphic; opens from World menu or via PosternDashboard open. Subscribes to Postern-Core announcements to render request traffic.