If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/darrenburns/posting shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6w ago
• 12 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 86% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live darrenburns/posting repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/darrenburns/posting.

What it runs against: a local clone of darrenburns/posting — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in darrenburns/posting | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 72 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of darrenburns/posting. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/darrenburns/posting.git
#   cd posting
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of darrenburns/posting and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "darrenburns/posting(\\.git)?\\b" \\
  && ok "origin remote is darrenburns/posting" \\
  || miss "origin remote is not darrenburns/posting (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/posting/app.py" \\
  && ok "src/posting/app.py" \\
  || miss "missing critical file: src/posting/app.py"
test -f "src/posting/collection.py" \\
  && ok "src/posting/collection.py" \\
  || miss "missing critical file: src/posting/collection.py"
test -f "src/posting/widgets/request/request_editor.py" \\
  && ok "src/posting/widgets/request/request_editor.py" \\
  || miss "missing critical file: src/posting/widgets/request/request_editor.py"
test -f "src/posting/commands.py" \\
  && ok "src/posting/commands.py" \\
  || miss "missing critical file: src/posting/commands.py"
test -f "src/posting/variables.py" \\
  && ok "src/posting/variables.py" \\
  || miss "missing critical file: src/posting/variables.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 72 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~42d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/darrenburns/posting"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Posting is a terminal-based (TUI) HTTP client built with Textual that replaces Postman/Insomnia for command-line workflows. It stores requests as simple YAML files for version control, features tree-sitter syntax highlighting, Vim keybindings, environment variables, Python pre/post-request scripting, and can import from curl commands, Postman collections, and OpenAPI specs. Monolithic Python application structured under src/ directory with Textual widgets as the core UI layer. Configuration stored in .codex/environments/environment.toml. Collections and requests persisted as YAML files in user's local filesystem. Test suite uses pytest (referenced in Makefile), SCSS/Jinja used for styling and templating, documentation site generated with mkdocs (mkdocs.yml present).

Backend developers, DevOps engineers, and API testers who work over SSH or prefer keyboard-driven workflows and want HTTP client functionality without leaving the terminal. Users who want request history versioned in Git and integrated with their editor ($EDITOR/$PAGER).

Actively developed and production-ready. The project has documented features in docs/guide/, comprehensive CI workflows (.github/workflows/ for tests, coverage, and docs), uses professional tooling (uv, pyproject.toml), and maintains a CHANGELOG.md. Single author (darrenburns) but well-structured with clear contribution guidelines.

Single-maintainer project with no visible governance structure documented. Python 3.13 requirement (specified in .python-version) may limit adoption. Risk from heavy dependency on Textual framework (external TUI library); any breaking changes there cascade directly. No visible security disclosure policy or formal issue triage process mentioned in accessible files.

Project is actively maintained with a documented roadmap (docs/roadmap.md) and recent addition of features like curl import, Postman/OpenAPI import, themes system (docs/guide/themes.md), and scripting capabilities (docs/guide/scripting.md). GitHub workflows show continuous testing and documentation deployment.

git clone https://github.com/darrenburns/posting.git
cd posting
uv sync
uv run posting

Alternatively with pip: pip install posting. Development setup uses uv as primary package manager per README and project structure.

Daily commands:

make test          # Run pytest suite
make coverage      # Generate coverage report
uv run posting     # Start the TUI client

Development workflows defined in Makefile; documentation builds via mkdocs.yml (see .github/workflows/docs.yml for CI).

• src/posting/app.py — Main application entry point and Textual app orchestration; contains core UI state management and request lifecycle handling.
• src/posting/collection.py — Core data model for HTTP requests and collections; defines serialization/deserialization to YAML and is the foundation for all request storage.
• src/posting/widgets/request/request_editor.py — Primary request editing widget; integrates all sub-editors (headers, body, auth, scripts) and manages request state mutations.
• src/posting/commands.py — Command palette and keyboard action dispatcher; defines all keybindings and command execution logic.
• src/posting/variables.py — Environment variable and substitution system; handles variable resolution in URLs, headers, and request bodies.
• src/posting/config.py — Configuration loading and user settings; manages themes, keybindings, and application preferences from YAML.
• src/posting/__main__.py — CLI entry point and argument parser; initializes app startup and handles environment setup.

Add a new HTTP request editor field (e.g., timeout, proxy settings)

1. Add property to Request dataclass in src/posting/collection.py (src/posting/collection.py)
2. Create a new widget subclass in src/posting/widgets/request/ following RequestBody or HeaderEditor pattern (src/posting/widgets/request/request_options.py)
3. Import and register the widget in request_editor.py's compose() method (src/posting/widgets/request/request_editor.py)
4. Handle the widget's message in request_editor.py's on_* message handler (src/posting/widgets/request/request_editor.py)
5. Update auth.py or urls.py if the field affects request execution (src/posting/auth.py)

Add a new command to the command palette

1. Define the action function in src/posting/commands.py (src/posting/commands.py)
2. Register keybinding in the COMMANDS dict in commands.py with description and callable (src/posting/commands.py)
3. Emit the action_XYZ message from relevant widget or handle_action in app.py (src/posting/app.py)
4. Test command discovery via command palette search (Ctrl+K) (src/posting/commands.py)

Add support for a new import format (beyond curl, Postman, OpenAPI)

1. Create new module src/posting/importing/format_name.py with parse function (src/posting/importing/open_api.py)
2. Parse input to list of (name: str, request: Request) tuples matching collection.py model (src/posting/collection.py)
3. Add import handler in app.py that detects format and calls your parser (src/posting/app.py)
4. Add UI action in commands.py to trigger import flow (src/posting/commands.py)

Add a new pre/post-request script capability

1. Extend script execution environment in src/posting/scripts.py (src/posting/scripts.py)
2. Define new variables/functions available to user scripts with documentation (src/posting/scripts.py)
3. Update request execution in app.py to pass new context when running pre/post scripts (src/posting/app.py)
4. Document new capability in docs/guide/scripting.md (docs/guide/scripting.md)

• Textual (TUI framework) — Enables terminal-based GUI with widgets, styling, and keyboard-first interaction; works over SSH without additional client setup.
• YAML for request storage — Human-readable, version-control-friendly format; easy to diff and merge; no binary lock-in.
• Python + httpx — Cross-platform HTTP client; async support for non-blocking requests; simple, feature-complete library.
• Tree-sitter for syntax highlighting — Fast incremental parsing for JSON, XML, etc.; accurate language-aware highlighting without external tools.
• Python script execution (pre/post-request) — Dynamic request/response manipulation; environment-specific logic; no need for separate scripting language.

• Terminal-only (no GUI desktop app)
  • Why: Simpler distribution, SSH-friendly, appeals to power users and DevOps workflows
  • Consequence: Limited to users comfortable

Python 3.13+ is hard-required (.python-version file), not negotiable; attempting to run on Python 3.12 will fail. Textual framework is a heavy dependency—UI behavior tied to Textual version; check CHANGELOG for breaking changes if updating. YAML files store requests; if user accidentally commits sensitive data (API keys in request bodies), it's in Git history permanently. Tree-sitter for syntax highlighting requires native library installation on some platforms. No documented way to migrate requests between machines or share them securely across teams (local YAML only). Environment variable expansion in requests may not behave as expected in all edge cases—test interpolation behavior.

• Tree-sitter syntax highlighting — Posting uses tree-sitter (not regex-based highlighting) for accurate JSON/YAML/code rendering in the TUI; understanding this is key to implementing new syntax features or debugging highlight bugs
• YAML for Configuration as Data — Unlike many CLI tools that use TOML/INI, Posting stores all requests as YAML files for Git-friendly version control; you must understand YAML structure to contribute request parsing/serialization logic
• Textual event-driven TUI architecture — Posting's entire UI is built on Textual's reactive/event model (widgets, message passing, focus management); any UI feature requires knowledge of Textual's event loop and widget lifecycle
• Environment variable interpolation & scoping — Posting supports pre-request Python scripts and environment variables (like Postman); implementing or fixing variable scope, substitution timing, or script execution order requires understanding this feature's state machine
• Curl command parsing & import — Posting can import curl commands by parsing them; this involves understanding curl's argument format, header encoding, and request body serialization to convert into internal request objects
• OpenAPI/Swagger spec parsing — Posting can import collections from OpenAPI specs; contributing to spec import means understanding OpenAPI structure, endpoint extraction, and schema resolution
• SSH-native TUI workflows — A core selling point of Posting over Postman; the entire UX is optimized for low-bandwidth, non-graphical SSH sessions; understanding terminal capabilities (terminfo, alternate screen buffer, ANSI codes) helps with compatibility issues

• httpie/httpie — Command-line HTTP client alternative; HTTPie is non-interactive (pure CLI) while Posting is interactive TUI—complementary approaches to terminal HTTP work
• textualize/textual — The TUI framework Posting is built on; any UI/rendering issues or feature requests depend on Textual's evolution
• getgrav/rest-client-ui — Another terminal REST client but less actively maintained; Posting is the modern replacement in this niche
• Orange-OpenSource/hurl — Declarative HTTP testing tool using .hurl files (like Posting's YAML); overlaps on request storage/version control but focuses on testing/automation rather than interactive exploration
• sreecodeslinger/gor — HTTP traffic replay tool; users of Posting may export requests and pipe to Gor for load testing or reproduction workflows

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/posting/auth.py

The auth.py module handles authentication logic (Basic, Bearer, Digest, etc.) but there are no visible test files in the repo structure for authentication. This is critical for an HTTP client where auth correctness directly impacts user security and API interactions. New contributors can write parameterized tests covering all auth schemes supported by the module.

• [ ] Create tests/test_auth.py with fixtures for different auth types
• [ ] Write tests for Basic authentication encoding/decoding
• [ ] Write tests for Bearer token handling
• [ ] Write tests for Digest authentication if supported
• [ ] Add tests for edge cases (empty credentials, special characters, invalid formats)
• [ ] Ensure tests are integrated into the test.yml GitHub workflow

Add integration tests for src/posting/importing/ modules (curl.py, postman.py, open_api.py)

The importing directory contains three parsers for different formats (curl commands, Postman collections, OpenAPI specs), but there are no visible test files validating their correctness. These are user-facing features where parsing failures would break workflows. New contributors can create realistic test fixtures and validate import accuracy.

• [ ] Create tests/test_importing/ directory with test_curl.py, test_postman.py, test_open_api.py
• [ ] Create tests/fixtures/ with sample curl commands, Postman JSON exports, and OpenAPI YAML specs
• [ ] Test curl.py: validate parsing of complex curl commands with headers, auth, body, etc.
• [ ] Test postman.py: validate importing collections with nested folders and variable substitution
• [ ] Test open_api.py: validate importing endpoints from OpenAPI 3.0/3.1 specs
• [ ] Test error handling for malformed/invalid inputs across all three parsers

Add unit tests for src/posting/collection.py and src/posting/config.py

These core modules handle request collection management and configuration parsing respectively. They likely interact with YAML files (src/posting/files.py) and are critical to the application's data model, but lack visible test coverage. New contributors can write tests for CRUD operations, file persistence, and configuration validation.

• [ ] Create tests/test_collection.py testing collection creation, loading, and modification
• [ ] Create tests/test_config.py testing configuration parsing and validation
• [ ] Write tests for collection.py: adding/removing requests, saving to YAML, loading from disk
• [ ] Write tests for config.py: parsing environment variables, keybindings, themes from config files
• [ ] Add tests for error scenarios (missing files, corrupt YAML, invalid config values)
• [ ] Test integration between collection.py and files.py for persistence

• Add test coverage for request serialization/deserialization to YAML (pyproject.toml shows pytest in use; likely src/ has untested YAML save/load logic). Check .coverage for gaps.
• Document the Python scripting API available in pre/post-request scripts (docs/guide/scripting.md exists but is likely sparse; add examples and API reference to docs/guide/scripting.md with docstrings from src/).
• Add keyboard shortcut hints to the help system (docs/guide/help_system.md and docs/guide/keymap.md exist separately; integrate them into contextual help or create a quick-reference popup in TUI).

• High · Potential Code Injection via Python Script Execution — src/posting/scripts.py. The codebase includes a scripts.py file and references to 'run Python code before and after requests' feature. This allows users to execute arbitrary Python code, which could be exploited if scripts are loaded from untrusted sources or if user input is not properly sanitized before execution. Fix: Implement strict sandboxing for Python script execution. Use restricted execution environments (e.g., RestrictedPython or similar), validate all script inputs, implement timeout limits, and provide clear security warnings to users about the risks of executing untrusted scripts.
• High · URL Import and cURL Command Parsing Vulnerabilities — src/posting/importing/curl.py, src/posting/importing/open_api.py, src/posting/importing/postman.py. The application imports requests from cURL commands and OpenAPI specs by parsing and executing user-provided input. This could lead to command injection, SSRF attacks, or header injection if the parsing logic doesn't properly validate and sanitize inputs. Fix: Implement strict input validation and sanitization for all import functions. Use safe parsing libraries, validate URLs against a whitelist if possible, sanitize headers and request bodies, and implement checks for potentially malicious payloads.
• High · Missing Dependency Security Information — pyproject.toml. The pyproject.toml file content was not provided in the analysis. This prevents verification of dependencies for known vulnerabilities, outdated packages, or malicious dependencies. Fix: Regularly run dependency security checks using tools like 'pip-audit', 'safety', or 'bandit'. Keep all dependencies up-to-date and review the security advisories for each dependency. Use lock files (pip-compile, poetry.lock) for reproducible builds.
• Medium · Potential Credential Exposure in Configuration Files — src/posting/collection.py, .codex/environments/environment.toml. The application stores requests locally in YAML files and includes environment/variables functionality. If authentication credentials (API keys, passwords, tokens) are stored in plaintext in these files, they could be exposed if the files are accidentally committed to version control or accessed by unauthorized users. Fix: Implement encryption for sensitive data at rest. Store credentials in a secure credential store or use environment variables. Add warnings when sensitive data is detected. Ensure .gitignore properly excludes credential files and implement pre-commit hooks to prevent accidental commits.
• Medium · Potential SSRF Vulnerability in HTTP Requests — src/posting/urls.py, src/posting/app.py. As an HTTP client that makes requests to user-specified URLs, the application could be vulnerable to Server-Side Request Forgery (SSRF) attacks if it doesn't validate URLs or allow access to internal/private IP ranges. Fix: Implement URL validation to reject requests to private IP ranges (127.0.0.1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, etc.). Use blocklists for dangerous protocols (file://, gopher://, etc.). Provide configuration options for URL restrictions.
• Medium · Auth Handling Without Visible Security Review — src/posting/auth.py. The auth.py file exists but its implementation details are not visible. Authentication mechanisms could have vulnerabilities if OAuth flows, API key handling, or credential storage are improperly implemented. Fix: Conduct a security code review of the authentication module. Ensure OAuth 2.0 flows follow best practices (PKCE for authorization code flow). Implement secure credential storage, use HTTPS only for auth endpoints, and avoid storing sensitive tokens in plaintext.
• Low · Missing Security Headers Documentation — src/posting/. No evidence of security headers validation or documentation in the visible files. While this is a TUI application (not web), any embedded server or API components should implement appropriate security headers. Fix: Document security considerations for users. If any embedded web components exist, ensure they implement Content-Security-Policy, X-Frame-Options, X-Content-Type-Options headers.
• Low · Potential Path Traversal in File Operations — undefined. The files.py module handles file operations for request/collection management. Without proper validation, path traversal attacks could occur when loading or saving Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.