Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 36 additions & 1 deletion .github/workflows/python-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,43 @@ jobs:
- name: Build release distributions
run: |
# NOTE: put your own distribution build steps here.
python -m pip install build
python -m pip install build twine trove-classifiers
python -m build
python -m twine check dist/*

- name: Validate classifiers against PyPI's list
# PyPI rejects any unknown classifier with a 400 during upload, so
# catch typos here instead of failing the publish step.
run: |
python - <<'EOF'
import pathlib, sys, tarfile, zipfile
from trove_classifiers import classifiers

valid = set(classifiers)
invalid = []
for path in sorted(pathlib.Path("dist").iterdir()):
if path.suffix == ".whl":
with zipfile.ZipFile(path) as archive:
name = next(n for n in archive.namelist() if n.endswith("METADATA"))
metadata = archive.read(name).decode("utf-8", "replace")
elif path.suffixes[-2:] == [".tar", ".gz"]:
with tarfile.open(path) as archive:
member = next(m for m in archive.getmembers() if m.name.endswith("PKG-INFO"))
metadata = archive.extractfile(member).read().decode("utf-8", "replace")
else:
continue
for line in metadata.splitlines():
if not line.startswith("Classifier: "):
continue
classifier = line.split(": ", 1)[1]
if classifier not in valid:
invalid.append(f"{classifier} (in {path.name})")

if invalid:
print("Invalid PyPI classifiers:", *invalid, sep="\n ")
sys.exit(1)
print("All classifiers are valid.")
EOF

- name: Upload distributions
uses: actions/upload-artifact@v4
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,6 @@ jobs:
fail-fast: false
matrix:
python-version: ["3.11", "3.13"]
env:
TIKTOKEN_CACHE_DIR: ${{ runner.temp }}/tiktoken
XDG_CONFIG_HOME: ${{ runner.temp }}/postal-config
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
Expand All @@ -36,6 +33,9 @@ jobs:
run: python -c "import tiktoken; tiktoken.get_encoding('cl100k_base')"
- name: Run Python tests
run: python -m pytest tests -q
env:
TIKTOKEN_CACHE_DIR: ${{ runner.temp }}/tiktoken
Comment on lines +36 to +37

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Tests miss the warmed cache

TIKTOKEN_CACHE_DIR now applies only to the test step. The earlier “Cache tokenizer data” step fills the default cache, while the tests use a separate directory and download the same data again. Give both steps the same value, preferably through a job-level env, so the tests reuse the downloaded data.

Prompt To Fix With AI
This is a comment left during a code review.
Path: .github/workflows/tests.yml
Line: 36-37

Comment:
**Tests miss the warmed cache**

`TIKTOKEN_CACHE_DIR` now applies only to the test step. The earlier “Cache tokenizer data” step fills the default cache, while the tests use a separate directory and download the same data again. Give both steps the same value, preferably through a job-level `env`, so the tests reuse the downloaded data.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

XDG_CONFIG_HOME: ${{ runner.temp }}/postal-config

terminal:
name: TypeScript terminal
Expand Down
2 changes: 1 addition & 1 deletion .postal/config.toml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ debug = false
# command='python3 ./scripts/test_tool.py'

[model]
name = "baidu/ernie-5.5-flash-preview:free"
name = "deepseek/deepseek-v4.1-flash-1017"
temperature = 1.0
context_window = 256000

Expand Down
29 changes: 22 additions & 7 deletions docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,36 +10,51 @@ Postal provides Docker support through a pre-built container image that includes

### Using Docker Compose

1. **Build and start the container**
Postal's interface is a full-screen terminal UI, so it needs an attached TTY.
Run it in the foreground rather than detached:

```bash
cd docker
API_KEY="your_openrouter_api_key" docker-compose up -d
API_KEY="your_openrouter_api_key" docker compose run --rm postal
```

2. **Connect to your workspace**
The service mounts your current directory (`$POSTAL_WORKSPACE:-..`) as
`/workspace` inside the container. Use `exit` (or Ctrl-C) to leave the UI; the
container is removed afterwards.

The container mounts your current directory (`$POSTAL_WORKSPACE:-..`) as `/workspace` inside the container. You can now interact with your code through Postal.
If you already started it detached with `docker compose up -d`, reattach with
`docker attach postal` — the UI is still running and waiting for input.

### Using Docker Image Directly

1. **Build the image**

```bash
docker build -t postal:dev ..
docker build -t postal:dev -f docker/Dockerfile ..

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Docker build paths conflict

The command mixes two working directories. From the repository root, docker/Dockerfile exists, but context .. makes COPY pyproject.toml README.md LICENSE /stub/ look outside the repository. From docker/, the context is right, but docker/Dockerfile does not exist. Use docker build -t postal:dev -f docker/Dockerfile . from the repository root.

Suggested change
docker build -t postal:dev -f docker/Dockerfile ..
docker build -t postal:dev -f docker/Dockerfile .
Prompt To Fix With AI
This is a comment left during a code review.
Path: docker/README.md
Line: 33

Comment:
**Docker build paths conflict**

The command mixes two working directories. From the repository root, `docker/Dockerfile` exists, but context `..` makes `COPY pyproject.toml README.md LICENSE /stub/` look outside the repository. From `docker/`, the context is right, but `docker/Dockerfile` does not exist. Use `docker build -t postal:dev -f docker/Dockerfile .` from the repository root.

```suggestion
docker build -t postal:dev -f docker/Dockerfile .
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

```

2. **Run the container**

`-it` is required: without a TTY the UI cannot start.

```bash
docker run -d \
docker run --rm -it \
--name postal \
-v "$(pwd):/workspace" \
-v "$(pwd)/.postal:/config" \
-v postal-config:/config \
-e API_KEY="your_openrouter_api_key" \
postal:dev
```

For a one-shot prompt instead of the interactive UI, no TTY is needed:

```bash
docker run --rm \
-v "$(pwd):/workspace" -v postal-config:/config \
-e API_KEY="your_openrouter_api_key" \
postal:dev "explain this codebase"
```

## Configuration

### Environment Variables
Expand Down
1 change: 0 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ classifiers = [
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Programming Language :: Python :: 3.14",
"Programming Language :: TypeScript",
"Topic :: Software Development",
]
dependencies = [
Expand Down
38 changes: 38 additions & 0 deletions tests/test_repl.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
import asyncio
import unittest
from unittest.mock import patch

from config.config import Config
from ui.repl.app import Repl


class ReplTerminalTests(unittest.TestCase):
def run_repl(self, isatty: bool):
with patch("ui.repl.app.sys.stdin") as stdin, patch("ui.repl.app.shutil.which") as which:
stdin.isatty.return_value = isatty
which.return_value = "/usr/bin/node"
with patch("ui.repl.app.asyncio.create_subprocess_exec") as spawn:
with self.assertRaises(RuntimeError) as raised:
asyncio.run(Repl(Config()).run())
Comment on lines +10 to +16

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Tests inherit the wrong interface

If a developer has the documented POSTAL_UI=textual setting, Repl.run() starts PostalApp before reaching the terminal check. These tests then exercise the wrong interface and can fail or wait for input. Clear or override POSTAL_UI in run_repl so both tests always select the TypeScript interface.

Prompt To Fix With AI
This is a comment left during a code review.
Path: tests/test_repl.py
Line: 10-16

Comment:
**Tests inherit the wrong interface**

If a developer has the documented `POSTAL_UI=textual` setting, `Repl.run()` starts `PostalApp` before reaching the terminal check. These tests then exercise the wrong interface and can fail or wait for input. Clear or override `POSTAL_UI` in `run_repl` so both tests always select the TypeScript interface.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

return raised.exception, which, spawn

def test_missing_tty_explains_how_to_run_in_docker(self):
error, which, spawn = self.run_repl(isatty=False)

message = str(error)
self.assertIn("needs a terminal", message)
self.assertIn("docker run -it", message)
self.assertIn("docker exec -it", message)
self.assertIn("postal \"your prompt\"", message)
which.assert_not_called()
spawn.assert_not_called()

def test_missing_tty_does_not_require_node(self):
error, which, _ = self.run_repl(isatty=False)

self.assertNotIn("Node.js", str(error))
which.assert_not_called()


if __name__ == "__main__":
unittest.main()
6 changes: 6 additions & 0 deletions ui/repl/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,12 @@ async def run(self) -> None:
from ui.textual_app import PostalApp
await PostalApp(self.config, resume=self.resume, upgrade_notice=self.upgrade_notice).run_async()
return
if not sys.stdin.isatty():
raise RuntimeError(
"The interactive TUI needs a terminal. Run `postal` from an interactive shell "
"(inside Docker use `docker run -it`, or `docker exec -it <container> postal`), "
"or pass a prompt instead: `postal \"your prompt\"`."
)
node = shutil.which("node")
if node is None:
raise RuntimeError("The TypeScript TUI requires Node.js 22+. Install Node, or set POSTAL_UI=textual to use the legacy interface.")
Expand Down
Loading