pxq 0.1.0__tar.gz

pxq-0.1.0/.github/RELEASE.md

@@ -0,0 +1,162 @@
+# PyPI Release Guide
+
+This document describes how to publish `pxq` to PyPI.
+
+## Prerequisites
+
+### 1. PyPI Account
+
+Create a PyPI account at https://pypi.org/account/ if you don't have one.
+
+### 2. Trusted Publisher Setup
+
+Trusted Publisher allows publishing to PyPI without API tokens, using GitHub OIDC.
+
+**Steps:**
+
+1. Go to https://pypi.org/manage/account/publishing/
+2. Click "Add a trusted publisher"
+3. Select "GitHub Actions"
+4. Fill in:
+   - **Project name**: `pxq`
+   - **Owner**: `takeru1205`
+   - **Repository name**: `pxq`
+   - **Workflow name**: `publish.yml`
+   - **Environment**: `pypi` (or leave blank for all environments)
+5. Click "Add"
+
+### 3. Create PyPI Project (First Time Only)
+
+For the first release:
+
+1. Go to https://pypi.org/project/pxq/
+2. If the project doesn't exist, create it with the name `pxq`
+3. Add the Trusted Publisher you created above
+
+## Release Process
+
+### Step 1: Update Version
+
+Update the version in `pyproject.toml`:
+
+```toml
+[project]
+name = "pxq"
+version = "0.1.0"  # Update this
+```
+
+**Versioning scheme**: Follow [Semantic Versioning](https://semver.org/)
+- `0.1.0` - Initial release
+- `0.1.1` - Bug fix
+- `0.2.0` - New feature
+
+### Step 2: Commit Changes
+
+```bash
+git add .
+git commit -m "Bump version to 0.1.0"
+git push origin main
+```
+
+### Step 3: Create GitHub Release
+
+**Via GitHub Web UI:**
+
+1. Go to https://github.com/takeru1205/pxq/releases
+2. Click "Draft a new release"
+3. Fill in:
+   - **Tag version**: `v0.1.0` (match the version with `v` prefix)
+   - **Release title**: `v0.1.0`
+   - **Description**: Add release notes (see template below)
+4. Click "Publish release"
+
+**Via GitHub CLI:**
+
+```bash
+gh release create v0.1.0 \
+  --title "v0.1.0" \
+  --notes "Release notes here" \
+  --generate-notes
+```
+
+### Step 4: Automatic PyPI Publish
+
+Once the release is published:
+
+1. GitHub Actions workflow `.github/workflows/publish.yml` is triggered automatically
+2. The workflow builds the package and publishes to PyPI
+3. Monitor the action at: https://github.com/takeru1205/pxq/actions
+
+### Step 5: Verify Publication
+
+Check that the package is published:
+
+- **PyPI**: https://pypi.org/project/pxq/
+- **Installation test**:
+  ```bash
+  pip install pxq
+  pxq --version
+  ```
+
+## Release Notes Template
+
+```markdown
+## What's Changed
+
+### New Features
+- Feature description
+
+### Bug Fixes
+- Fix description
+
+### Improvements
+- Improvement description
+
+## Installation
+
+```bash
+# From PyPI
+pip install pxq
+
+# Or with uv
+uv tool install pxq
+
+# From GitHub (latest)
+uv tool install git+https://github.com/takeru1205/pxq.git
+```
+
+**Full Changelog**: https://github.com/takeru1205/pxq/compare/v0.0.0...v0.1.0
+```
+
+## Troubleshooting
+
+### Workflow Fails
+
+**Check the logs at**: https://github.com/takeru1205/pxq/actions
+
+Common issues:
+- **Trusted Publisher not configured**: Verify the publisher setup in PyPI
+- **Version already exists**: Bump the version number
+- **Build errors**: Check `uv build` output locally
+
+### Package Name Already Taken
+
+If `pxq` is already taken on PyPI:
+- You cannot publish with the same name
+- Consider a different name or contact the current owner
+
+### Manual Publish (Fallback)
+
+If Trusted Publisher fails, use API token:
+
+```bash
+# Add token as GitHub Secret: PYPI_TOKEN
+# Then modify publish.yml to use:
+- run: uv publish --token ${{ secrets.PYPI_TOKEN }}
+```
+
+## Version History
+
+| Version | Date | Notes |
+|---------|------|-------|
+| 0.1.0 | TBD | Initial release |

pxq-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write  # Required for Trusted Publisher
+  contents: read
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pxq
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      
+      - name: Set up Python
+        run: uv python install 3.11
+      
+      - name: Build package
+        run: uv build
+      
+      - name: Publish to PyPI
+        run: uv publish

pxq-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.sisyphus/

pxq-0.1.0/.hive/issues.jsonl

@@ -0,0 +1,15 @@
+{"id":"cell-4qpa5z-mmgc5grykrf","title":"Allow dashboard users to view logs for completed jobs","description":"Enable pxqueue dashboard users to view actual log content (stdout/stderr) for completed jobs. Current system only stores artifact metadata (paths, sizes) without content, making logs inaccessible after pod termination.","status":"open","priority":1,"issue_type":"epic","created_at":"2026-03-07T13:04:50.734Z","updated_at":"2026-03-07T13:04:50.734Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmgc5gs5kvu","title":"Design log content storage schema and add content column to artifacts table","status":"open","priority":3,"issue_type":"task","created_at":"2026-03-07T13:04:50.741Z","updated_at":"2026-03-07T13:04:50.741Z","parent_id":"cell-4qpa5z-mmgc5grykrf","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmgc5gs7b5p","title":"Update storage.py to persist actual log content bytes","status":"open","priority":2,"issue_type":"task","created_at":"2026-03-07T13:04:50.743Z","updated_at":"2026-03-07T13:04:50.743Z","parent_id":"cell-4qpa5z-mmgc5grykrf","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmgc5gs7tqe","title":"Add final log collection hook when job transitions to terminal state","status":"open","priority":3,"issue_type":"task","created_at":"2026-03-07T13:04:50.743Z","updated_at":"2026-03-07T13:04:50.743Z","parent_id":"cell-4qpa5z-mmgc5grykrf","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmgc5gs8psl","title":"Modify log_collector.py to capture and pass content to create_artifact()","status":"open","priority":2,"issue_type":"task","created_at":"2026-03-07T13:04:50.744Z","updated_at":"2026-03-07T13:04:50.744Z","parent_id":"cell-4qpa5z-mmgc5grykrf","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmgc5gs9tg1","title":"Update dashboard templates to display actual log content","status":"open","priority":2,"issue_type":"task","created_at":"2026-03-07T13:04:50.745Z","updated_at":"2026-03-07T13:04:50.745Z","parent_id":"cell-4qpa5z-mmgc5grykrf","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmgc5gsalpq","title":"Add API endpoint for log content retrieval","status":"open","priority":1,"issue_type":"task","created_at":"2026-03-07T13:04:50.746Z","updated_at":"2026-03-07T13:04:50.746Z","parent_id":"cell-4qpa5z-mmgc5grykrf","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmgc5gsblkl","title":"Add integration tests for completed-job log viewing","status":"open","priority":2,"issue_type":"task","created_at":"2026-03-07T13:04:50.747Z","updated_at":"2026-03-07T13:04:50.747Z","parent_id":"cell-4qpa5z-mmgc5grykrf","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmh9hngzu6t","title":"RunPod stderr verification flow + documentation","description":"Create verification flow for RunPod stderr capture that proves stderr content renders in the dashboard with proper cleanup. Includes: (1) integration test with --run-integration flag, (2) manual verification script, (3) documentation updates to examples/runpod/README.md, (4) DB and dashboard HTML verification commands.","status":"open","priority":1,"issue_type":"epic","created_at":"2026-03-08T04:38:06.611Z","updated_at":"2026-03-08T04:38:06.611Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmh9hnh6ch9","title":"Analyze test_output.py and verify it produces stderr","status":"open","priority":2,"issue_type":"task","created_at":"2026-03-08T04:38:06.618Z","updated_at":"2026-03-08T04:38:06.618Z","parent_id":"cell-4qpa5z-mmh9hngzu6t","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmh9hnh99oz","title":"Research existing integration test patterns","status":"open","priority":2,"issue_type":"task","created_at":"2026-03-08T04:38:06.621Z","updated_at":"2026-03-08T04:38:06.621Z","parent_id":"cell-4qpa5z-mmh9hngzu6t","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmh9hnhbtwm","title":"Create stderr verification integration test","status":"open","priority":1,"issue_type":"task","created_at":"2026-03-08T04:38:06.623Z","updated_at":"2026-03-08T04:38:06.623Z","parent_id":"cell-4qpa5z-mmh9hngzu6t","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmh9hnhg33c","title":"Create manual verification script","status":"open","priority":2,"issue_type":"task","created_at":"2026-03-08T04:38:06.628Z","updated_at":"2026-03-08T04:38:06.628Z","parent_id":"cell-4qpa5z-mmh9hngzu6t","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmh9hnhgdfp","title":"Update RunPod README with stderr verification section","status":"open","priority":2,"issue_type":"task","created_at":"2026-03-08T04:38:06.628Z","updated_at":"2026-03-08T04:38:06.628Z","parent_id":"cell-4qpa5z-mmh9hngzu6t","dependencies":[],"labels":[],"comments":[]}
+{"id":"cell-4qpa5z-mmh9hnhhl5y","title":"Add DB and dashboard verification commands to test","status":"open","priority":1,"issue_type":"task","created_at":"2026-03-08T04:38:06.629Z","updated_at":"2026-03-08T04:38:06.629Z","parent_id":"cell-4qpa5z-mmh9hngzu6t","dependencies":[],"labels":[],"comments":[]}

pxq-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

pxq-0.1.0/.tmp/design.md

@@ -0,0 +1,144 @@
+# Server Identity and Stale PID Reconciliation Design
+
+## Overview
+
+This document defines the canonical server identity verification logic for pxq server. The goal is to reliably detect the actual pxq server process even when the PID file contains a stale PID, and to guard against accidentally touching non-pxq processes.
+
+## Problem Statement
+
+### Current Issues
+
+1. **Stale PID File**: The PID file (`~/.pxq/server.pid`) may contain a PID that no longer exists or belongs to a different process.
+2. **No Identity Verification**: Current implementation only checks if a process with the PID exists via `os.kill(pid, 0)`, but does not verify if it's actually the pxq server.
+3. **False Positives**: If another process happens to get the same PID, the current code incorrectly assumes it's the pxq server.
+4. **No Port Ownership Check**: The current code doesn't verify if the process is actually listening on the expected server port.
+
+### Known Issues from Context
+
+- Live server (PID 28692) and PID file (dead PID 35336) were mismatched
+- Live server's openapi was missing `/api/jobs/stop` and `/api/jobs/{job_id}/cancel` endpoints
+- `pxq cancel 28` (provisioning) returned 404 because the server wasn't properly detected
+
+## Solution Design
+
+### Core Principles
+
+1. **Port-based Detection**: The true pxq server is identified by the process listening on `server_host:server_port` (default 127.0.0.1:8765).
+2. **Identity Verification**: Verify the process is actually pxq server by checking its command line contains `uvicorn pxq.server:app`.
+3. **Stale PID Handling**: Automatically detect and clean up stale PID files.
+4. **Safety Guard**: Never touch a process that doesn't match the pxq server identity.
+
+### Function Definitions
+
+#### `get_pxq_server_pid() -> Optional[int]`
+
+Returns the PID of the actual pxq server process, ignoring stale PID files.
+
+**Algorithm**:
+1. Get the configured server port (default 8765)
+2. Use `lsof -ti:{port}` to find the PID listening on that port
+3. If no process is listening on the port, return None
+4. Verify the process is pxq server by checking cmdline contains `uvicorn pxq.server:app` or `pxq.server:app`
+5. If identity verified, return the PID
+6. If identity not verified, return None (non-pxq process owns the port)
+
+**Edge Cases**:
+- No process listening on port → return None
+- Multiple PIDs from lsof → use the first one (single instance design)
+- Permission denied on lsof → fallback to reading PID file with identity check
+- Non-pxq process owns the port → return None (safety guard)
+
+#### `is_pxq_server_running() -> bool`
+
+Returns True if the actual pxq server is running.
+
+**Implementation**:
+- Returns `get_pxq_server_pid() is not None`
+
+#### `cleanup_stale_pid() -> bool`
+
+Removes the stale PID file if it doesn't match the actual pxq server.
+
+**Algorithm**:
+1. Get the actual pxq server PID via `get_pxq_server_pid()`
+2. Read the PID file via `read_pid()`
+3. If PID file doesn't exist, return False (nothing to clean)
+4. If actual server PID matches PID file, return False (not stale)
+5. If actual server PID is None (no server) or different from PID file:
+   - Delete the PID file
+   - Return True (cleaned up stale file)
+
+### Identity Verification Details
+
+**Process Identity Check**:
+- Read `/proc/{pid}/cmdline` (Linux) or use `ps` command (macOS)
+- Check if cmdline contains any of:
+  - `uvicorn pxq.server:app`
+  - `pxq.server:app`
+  - `pxq.server:create_app`
+
+**Port Ownership Check**:
+- Use `lsof -ti:{port}` to get PID listening on the port
+- This is more reliable than trusting the PID file
+
+### Platform Support
+
+- **macOS**: Use `lsof -ti:{port}` and `ps -p {pid} -o command=`
+- **Linux**: Use `lsof -ti:{port}` and read `/proc/{pid}/cmdline`
+
+### Error Handling
+
+1. **lsof not available**: Fallback to PID file check with identity verification
+2. **Permission denied**: Handle gracefully, return None
+3. **Process exits between checks**: Return None
+
+## Testing Strategy
+
+### Unit Tests
+
+1. **Stale PID reconciliation happy path**:
+   - PID file contains dead PID
+   - Actual pxq server running on port
+   - `get_pxq_server_pid()` returns actual server PID
+   - `cleanup_stale_pid()` removes stale PID file
+
+2. **Non-pxq listener failure guard**:
+   - Non-pxq process listening on port 8765
+   - `get_pxq_server_pid()` returns None
+   - `is_pxq_server_running()` returns False
+
+3. **Normal operation**:
+   - pxq server running, PID file correct
+   - All functions work correctly
+
+4. **No server running**:
+   - No process on port, no PID file
+   - All functions return None/False
+
+### Test Commands
+
+```bash
+# Scenario 1: stale PID reconciliation happy path
+uv run pytest tests/unit -k "server_pid or stale pid or listener" -q | tee .sisyphus/evidence/task-1-server-identity.txt
+
+# Scenario 2: non-pxq listener failure guard
+uv run pytest tests/unit -k "non pxq listener or foreign process" -q | tee .sisyphus/evidence/task-1-server-identity-error.txt
+```
+
+## Dependencies
+
+- This task is Wave 1 foundation task
+- Task 2, 3, 4 depend on this task
+- No external dependencies
+
+## Files to Modify
+
+- `src/pxq/server_pid.py` - Add new functions
+- `tests/unit/test_server_pid.py` - Add new test cases
+- `src/pxq/cli.py` - Update to use new functions (if needed)
+
+## Backward Compatibility
+
+- Existing functions (`get_server_pid()`, `is_server_running()`) remain unchanged
+- New functions are additions, not replacements
+- CLI commands continue to work with existing functions initially

pxq-0.1.0/.tmp/task.md

@@ -0,0 +1,70 @@
+# Task List: Server Identity and Stale PID Reconciliation
+
+## Wave 1: Foundation Task
+
+### Task 1: Define canonical server identity and stale-state reconciliation
+
+**Status**: In Progress
+
+**Description**: 
+Define the canonical server identity verification logic. Add functions to `src/pxq/server_pid.py` to:
+- Detect actual pxq server process by port ownership and cmdline identity
+- Clean up stale PID files automatically
+- Guard against touching non-pxq processes
+
+**Subtasks**:
+
+- [x] Create design document (.tmp/design.md)
+- [ ] Create task list (.tmp/task.md)
+- [ ] Implement `get_pxq_server_pid()` function
+  - Use `lsof -ti:{port}` to find process listening on server port
+  - Verify process identity via cmdline check
+  - Return None if no pxq server found or non-pxq process owns port
+- [ ] Implement `is_pxq_server_running()` function
+  - Wrapper around `get_pxq_server_pid()`
+- [ ] Implement `cleanup_stale_pid()` function
+  - Compare PID file with actual server PID
+  - Remove stale PID file
+- [ ] Add unit tests for new functions
+  - Test stale PID reconciliation happy path
+  - Test non-pxq listener failure guard
+  - Test normal operation
+  - Test no server running
+- [ ] Run pytest and verify all tests pass
+- [ ] Save pytest output to .sisyphus/evidence/
+- [ ] Create learnings document
+
+**Dependencies**: None (foundation task)
+
+**Dependent Tasks**: 
+- Task 2: TBD
+- Task 3: TBD
+- Task 4: TBD
+
+**Files to Modify**:
+- `src/pxq/server_pid.py` - Add new functions
+- `tests/unit/test_server_pid.py` - Add test cases
+
+**Test Commands**:
+```bash
+# Run all server_pid tests
+uv run pytest tests/unit/test_server_pid.py -v
+
+# Run specific test categories
+uv run pytest tests/unit -k "server_pid or stale pid or listener" -q
+```
+
+**Acceptance Criteria**:
+- [ ] `get_pxq_server_pid()` returns actual pxq server PID (not stale PID)
+- [ ] `get_pxq_server_pid()` returns None for non-pxq process on port
+- [ ] `is_pxq_server_running()` accurately reflects pxq server status
+- [ ] `cleanup_stale_pid()` removes stale PID files
+- [ ] All existing tests continue to pass (no regression)
+- [ ] New tests cover all scenarios
+- [ ] pytest output saved to .sisyphus/evidence/
+
+## Notes
+
+- Platform: macOS (primary), Linux (secondary)
+- Default server port: 8765
+- Server identity: process running `uvicorn pxq.server:app`