journeyman-cli 1.1.0__tar.gz

journeyman_cli-1.1.0/.github/workflows/publish.yml

@@ -0,0 +1,77 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  security-and-tests:
+    name: Security Audits & Unit Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools
+          python -m pip install bandit pip-audit ruff
+
+      - name: Lint and Code Style Check (Ruff)
+        run: ruff check src/
+
+      - name: Security Code Analysis (Bandit)
+        # B310: urllib.request.urlopen (we mock/handle this securely)
+        # B404/B603: subprocess usage (required for compiling/validating)
+        # We skip these specific warnings or run bandit to catch other high-severity issues.
+        run: bandit -r src/ -x tests/ --skip B310,B404,B603
+
+      - name: Dependency Vulnerability Audit (pip-audit)
+        run: pip-audit
+
+      - name: Run Unit Tests
+        run: |
+          PYTHONPATH=src python3 -m unittest discover -s tests -v
+
+  build-n-publish:
+    name: Build and publish Python 🐍 distribution 📦 to PyPI
+    needs: security-and-tests
+    # Only publish on tag pushes or release triggers, not on standard pull requests
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for Trusted Publishing (OIDC) to PyPI
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade pip setuptools build
+
+      - name: Build binary wheel and source tarball
+        run: python -m build
+
+      - name: Publish package distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

journeyman_cli-1.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Spec files and worker artifacts
+tasks/*.md
+*.bak
+*.partial
+.sb_tmp_*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*~
+
+# Local / secrets (never commit)
+.env
+.env.*
+!.env.example

journeyman_cli-1.1.0/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes to **journeyman** are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+---
+
+## [1.1.0] — 2026-07-26
+
+### Added
+
+#### Cost tracking
+- **Per-call cost line** on stderr after every successful worker run:
+  `[journeyman] 1,252 tokens (840 in + 412 out) | est. cost: $0.00007`
+  Local models always show `$0.000`. Falls back to "Token count unavailable" when
+  the provider does not return usage data.
+- **Usage log** at `~/.local/share/journeyman/usage.jsonl` (overridable via
+  `JOURNEYMAN_USAGE_LOG`); every successful run appends one JSON line with provider,
+  model, token counts, estimated cost, output file, and UTC timestamp.
+- **`journeyman stats`** command — reads the usage log and prints a grouped summary
+  table (provider / model / run count / total tokens / estimated cost); supports
+  `--since DAYS` and `--json` flags.
+- **`MODEL_PRICING`** table in `constants.py` — approximate mid-2025 list prices for
+  all built-in remote providers; local providers always resolve to `$0.00`.
+
+#### Agent integration
+- **Templates** for wiring journeyman into frontier agents (in `templates/`):
+  - `CLAUDE.md` — Claude Code
+  - `AGENTS.md` — Codex CLI
+  - `cursorrules` — Cursor
+  - `GEMINI.md` — Gemini CLI
+  - `copilot-instructions.md` — GitHub Copilot
+  - `journeyman.mdc` — Cursor MDC rules format
+- `install.sh` post-install tip now lists all template filenames explicitly.
+
+#### CLI flags
+- `--json-output` — write a structured JSON summary to stdout on exit; stdout is
+  otherwise silent (safe to pipe to `jq` or capture in a script).
+- `--root DIR` — set project root; all relative `--task`, `--out`, and `--context`
+  paths resolve from here (useful when agent CWD ≠ project root).
+- `--task -` — read spec from stdin instead of a file; preferred invocation pattern
+  for autonomous agents (no temp-file round-trip).
+- `--timeout SECONDS` — override the default 120 s HTTP timeout for model API calls.
+
+#### Tooling
+- `journeyman version` command (`journeyman --version` also works).
+- Python 3.7+ version check in `journeyman.sh` with a clear error message.
+- `USAGE_LOG_PATH` added to `constants.py` (overridable via `JOURNEYMAN_USAGE_LOG`).
+- Dynamic provider lists in error messages — all messages now derive from
+  `VALID_REMOTE_PROVIDERS` in `constants.py`, so adding a new provider auto-updates
+  every error string.
+
+### Changed
+
+- **Streaming** (`--stream`) now writes to **stderr**, keeping **stdout** clean for
+  `--json-output`; `stream_options: {"include_usage": true}` is also sent so token
+  counts are available even for streamed responses.
+- **README** completely rewritten — punchy hook, architecture diagram, agent
+  integration table, full CLI options, exit-code reference, and data flow & trust section.
+- `install.sh` tip message now lists each template filename on its own line.
+
+### Fixed
+
+- **Context injection backtick corruption** — context files are now injected using
+  `=== Context: name ===` / `=== End: name ===` delimiters instead of triple-backtick
+  fences, so context files that contain `` ``` `` can no longer corrupt the
+  code-extraction regex.
+- **`OSError` on directory paths** — passing a directory as `--context` or `--task`
+  (e.g. `--context src/`) previously crashed with an unhandled `IsADirectoryError`;
+  now exits cleanly with code 2 and a descriptive message.
+
+### Tests
+
+- Test count: **66 → 119** (all passing).
+- New test classes:
+  - `TestStdinSpec` — `--task -` stdin invocation and content forwarding
+  - `TestJsonOutput` — `--json-output` success and failure paths
+  - `TestContextSizeWarning` — 32 KB context threshold warning
+  - `TestRootFlag` — relative path resolution with `--root`
+  - `TestCostTracking` — `estimate_cost`, `append_usage_log`, usage field in JSON output
+  - `TestUtf8Reads` — binary context file exits with code 2
+  - `TestFormatContextSnippet` — `===` delimiter correctness and code-extraction safety
+
+---
+
+## [1.0.0] — 2026-07-18
+
+Initial release.
+
+### Added
+
+- `journeyman worker` — sends a one-file spec to a local or economical model, validates
+  syntax (`py_compile`, `node --check`, `bash -n`, `tsc --noEmit`), and atomically
+  writes the output file with a `.bak` of the previous version.
+- `journeyman setup` — interactive and flag-driven configuration of local/remote backends;
+  stores config in `~/.config/journeyman/config.json` (mode 0600 for keys).
+- `journeyman detect` — probe and display the active backend.
+- **Auto-detection** — local backends probed on startup in priority order:
+  Ollama (11434) → LM Studio (1234) → llama.cpp / mlx_lm (8080); remote fallback uses
+  the first provider with a key set: Groq → Together AI → Gemini → OpenAI.
+- `--expect PATTERN` — regex that must appear in generated code; retried up to 2× with
+  the failure fed back to the model.
+- `--stream` — display generated content as it arrives.
+- `--lang` — override language detection from file extension
+  (`python`, `javascript`, `typescript`, `bash`).
+- `--no-validate` / `--no-backup` — opt-out flags.
+- `install.sh` — link and copy installation modes; `--uninstall` support; registers
+  the skill under `~/.claude/skills/journeyman/` for Claude Code discovery.
+- `SKILL.md` — agent-readable skill definition with full workflow and exit-code contract.
+- `references/REVIEW.md` — human review protocol for code generated by the worker.
+- Exit codes: `0` success, `1` no code block, `2` config/network error,
+  `3` validation failed, `4` stream interrupted, `5` `--expect` pattern absent after
+  retries.
+- 66 unit tests covering `extract_code`, `detect_backend`, `_auth_header`,
+  `write_atomic`, retry logic, and setup commands.
+- `scripts/constants.py` — single source of truth for all backend definitions,
+  provider env vars, and config path.
+- `scripts/backend_util.py` — shared config load/save, model listing, and local model
+  selection helpers.
+
+[Unreleased]: https://github.com/RajatGarg97/journeyman/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/RajatGarg97/journeyman/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/RajatGarg97/journeyman/releases/tag/v1.0.0

journeyman_cli-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 journeyman contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

journeyman_cli-1.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: journeyman-cli
+Version: 1.1.0
+Summary: Route implementation tasks to a local or economical model
+Author: Rajat Garg
+License: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# journeyman
+
+**Save your frontier tokens for thinking. A local or economical model writes every line of code — and tight specs make small models write it well.**
+
+`journeyman` is an Agent Skill designed to plug into **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, and **Gemini CLI**. It is built on a simple division of labor:
+1. **The Frontier Agent (Claude/GPT/Gemini)** acts as the architect. It writes plans, tests, and highly specific per-file specs. It *never* writes the application source code directly.
+2. **The Worker Model (Local or Low-Cost Remote)** types out the actual code based on those tight specs.
+
+By enforcing this contract, you save expensive API tokens on repetitive code generation, and you force small models to generate high-quality code because they are never given vague prompts.
+
+---
+
+## Quick Start
+
+### 1. Install the CLI
+
+You can install `journeyman` directly as a Python package from the repository root:
+
+```bash
+git clone <this-repo-url> journeyman
+cd journeyman
+pip install .
+```
+
+Alternatively, you can run `./install.sh` which runs `pip install` and registers the skill for Claude Code under `~/.claude/skills/journeyman`. (Use `./install.sh --copy` for a standalone copy-mode installation.)
+
+### 2. Configure your Worker Model
+
+`journeyman` is zero-config if you run a local model server. It automatically detects and connects to **Ollama** (port 11434), **LM Studio** (1234), **llama.cpp**, and **mlx_lm** (8080).
+
+If you don't have local hardware, you can fall back to fast, low-cost remote providers:
+
+```bash
+# See all available backends (local and remote)
+journeyman setup --list
+
+# Set a preferred remote fallback (requires GROQ_API_KEY in your environment)
+journeyman setup --prefer-remote groq
+
+# Or store a key in the config file (mode 0600; env vars still win)
+journeyman setup --set-api-key groq "$GROQ_API_KEY"
+```
+
+### 3. Integrate with your Agent
+
+Journeyman ships with ready-to-paste integration templates. Just copy the contents of the relevant file into your project:
+
+| Agent | File to edit | Template to copy |
+|---|---|---|
+| **Claude Code** | `CLAUDE.md` in project root | `templates/CLAUDE.md` |
+| **Codex CLI** | `AGENTS.md` in project root | `templates/AGENTS.md` |
+| **Cursor** (current) | `.cursor/rules/journeyman.mdc` | `templates/journeyman.mdc` |
+| **Cursor** (legacy) | `.cursorrules` in project root | `templates/cursorrules` |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | `templates/copilot-instructions.md` |
+| **Gemini CLI** | `GEMINI.md` in project root | `templates/GEMINI.md` |
+
+Once added, just tell your agent: *"Use journeyman to build a CLI todo app."*
+
+---
+
+## How it Works
+
+```text
+you ──"build X"──▶ frontier agent (Claude / Gemini / GPT)
+                     │  1. writes architecture and per-file specs
+                     │  2. invokes journeyman ──▶ local or economical model
+                     │                         (writes the file)
+                     │  3. reviews the code, runs tests
+                     │  4. on failure: improves the SPEC and re-delegates
+                     ▼
+                 working, reviewed code — written locally or via a low-cost remote
+```
+
+The worker script (`journeyman worker`) validates the generated code (Python: `py_compile`; JS: `node --check`; TS: `tsc --noEmit`; Bash: `bash -n`) and handles automatic retries if the local model messes up, before passing control back to the frontier agent for final review.
+
+---
+
+## Manual CLI Usage
+
+You can use `journeyman` manually without an agent. The worker takes a markdown spec and outputs a validated file:
+
+```bash
+# Pipe a spec directly (preferred for agents)
+journeyman worker --task - --out src/parser.py --expect 'class Parser' <<'SPEC'
+# Task: Create a CSV parser
+## Output file
+src/parser.py
+## Language & Runtime
+Python 3.11+
+## Signatures
+class Parser: ...
+SPEC
+
+# Or use a spec file
+journeyman worker --task tasks/01-parser.md --out src/parser.py --stream
+```
+
+### CLI Options
+
+| Flag | Description |
+|---|---|
+| `--task FILE` | Spec file (Markdown), or `-` for stdin |
+| `--out FILE` | Output file path |
+| `--context FILE...` | Read-only context files to inject |
+| `--expect PATTERN` | Regex that must appear in output |
+| `--json-output` | Write JSON result summary to stdout (for agent consumption) |
+| `--stream` | Show output as it is generated (to stderr) |
+| `--lang` | Override auto-detected language (`python`, `javascript`, `typescript`, `bash`) |
+| `--no-validate` | Skip syntax check |
+| `--no-backup` | Overwrite without creating a `.bak` copy |
+| `--timeout SECONDS` | HTTP timeout for model API calls (default: 120) |
+| `--root DIR` | Project root; relative paths resolve from here |
+
+---
+
+## Requirements & Trust
+
+- **Python 3.7+** (No external dependencies; standard library only).
+- **Data flow**: If you use a local backend (Ollama/LM Studio), **no data leaves your machine**. If you use a remote fallback, specs and injected context files are sent to that API.
+- **Safety**: `journeyman` performs atomic writes. If a file exists, it automatically creates a `.bak` copy before overwriting.
+
+## Exit Codes
+
+Agents rely on strict exit codes to manage the workflow:
+
+| Code | Meaning | Agent Action |
+|---|---|---|
+| **0** | Success — validated output written | Review the output |
+| **1** | No code block in response | Tighten spec and retry |
+| **2** | Config, argument, or network error | Do NOT retry; ask user to check setup |
+| **3** | Validation failed after max retries | Fix the file directly |
+| **4** | Stream interrupted | Retry |
+| **5** | `--expect` pattern missing after retries | Tighten expect/signatures; retry |
+
+---
+*License: MIT*

journeyman_cli-1.1.0/README.md

@@ -0,0 +1,136 @@
+# journeyman
+
+**Save your frontier tokens for thinking. A local or economical model writes every line of code — and tight specs make small models write it well.**
+
+`journeyman` is an Agent Skill designed to plug into **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, and **Gemini CLI**. It is built on a simple division of labor:
+1. **The Frontier Agent (Claude/GPT/Gemini)** acts as the architect. It writes plans, tests, and highly specific per-file specs. It *never* writes the application source code directly.
+2. **The Worker Model (Local or Low-Cost Remote)** types out the actual code based on those tight specs.
+
+By enforcing this contract, you save expensive API tokens on repetitive code generation, and you force small models to generate high-quality code because they are never given vague prompts.
+
+---
+
+## Quick Start
+
+### 1. Install the CLI
+
+You can install `journeyman` directly as a Python package from the repository root:
+
+```bash
+git clone <this-repo-url> journeyman
+cd journeyman
+pip install .
+```
+
+Alternatively, you can run `./install.sh` which runs `pip install` and registers the skill for Claude Code under `~/.claude/skills/journeyman`. (Use `./install.sh --copy` for a standalone copy-mode installation.)
+
+### 2. Configure your Worker Model
+
+`journeyman` is zero-config if you run a local model server. It automatically detects and connects to **Ollama** (port 11434), **LM Studio** (1234), **llama.cpp**, and **mlx_lm** (8080).
+
+If you don't have local hardware, you can fall back to fast, low-cost remote providers:
+
+```bash
+# See all available backends (local and remote)
+journeyman setup --list
+
+# Set a preferred remote fallback (requires GROQ_API_KEY in your environment)
+journeyman setup --prefer-remote groq
+
+# Or store a key in the config file (mode 0600; env vars still win)
+journeyman setup --set-api-key groq "$GROQ_API_KEY"
+```
+
+### 3. Integrate with your Agent
+
+Journeyman ships with ready-to-paste integration templates. Just copy the contents of the relevant file into your project:
+
+| Agent | File to edit | Template to copy |
+|---|---|---|
+| **Claude Code** | `CLAUDE.md` in project root | `templates/CLAUDE.md` |
+| **Codex CLI** | `AGENTS.md` in project root | `templates/AGENTS.md` |
+| **Cursor** (current) | `.cursor/rules/journeyman.mdc` | `templates/journeyman.mdc` |
+| **Cursor** (legacy) | `.cursorrules` in project root | `templates/cursorrules` |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | `templates/copilot-instructions.md` |
+| **Gemini CLI** | `GEMINI.md` in project root | `templates/GEMINI.md` |
+
+Once added, just tell your agent: *"Use journeyman to build a CLI todo app."*
+
+---
+
+## How it Works
+
+```text
+you ──"build X"──▶ frontier agent (Claude / Gemini / GPT)
+                     │  1. writes architecture and per-file specs
+                     │  2. invokes journeyman ──▶ local or economical model
+                     │                         (writes the file)
+                     │  3. reviews the code, runs tests
+                     │  4. on failure: improves the SPEC and re-delegates
+                     ▼
+                 working, reviewed code — written locally or via a low-cost remote
+```
+
+The worker script (`journeyman worker`) validates the generated code (Python: `py_compile`; JS: `node --check`; TS: `tsc --noEmit`; Bash: `bash -n`) and handles automatic retries if the local model messes up, before passing control back to the frontier agent for final review.
+
+---
+
+## Manual CLI Usage
+
+You can use `journeyman` manually without an agent. The worker takes a markdown spec and outputs a validated file:
+
+```bash
+# Pipe a spec directly (preferred for agents)
+journeyman worker --task - --out src/parser.py --expect 'class Parser' <<'SPEC'
+# Task: Create a CSV parser
+## Output file
+src/parser.py
+## Language & Runtime
+Python 3.11+
+## Signatures
+class Parser: ...
+SPEC
+
+# Or use a spec file
+journeyman worker --task tasks/01-parser.md --out src/parser.py --stream
+```
+
+### CLI Options
+
+| Flag | Description |
+|---|---|
+| `--task FILE` | Spec file (Markdown), or `-` for stdin |
+| `--out FILE` | Output file path |
+| `--context FILE...` | Read-only context files to inject |
+| `--expect PATTERN` | Regex that must appear in output |
+| `--json-output` | Write JSON result summary to stdout (for agent consumption) |
+| `--stream` | Show output as it is generated (to stderr) |
+| `--lang` | Override auto-detected language (`python`, `javascript`, `typescript`, `bash`) |
+| `--no-validate` | Skip syntax check |
+| `--no-backup` | Overwrite without creating a `.bak` copy |
+| `--timeout SECONDS` | HTTP timeout for model API calls (default: 120) |
+| `--root DIR` | Project root; relative paths resolve from here |
+
+---
+
+## Requirements & Trust
+
+- **Python 3.7+** (No external dependencies; standard library only).
+- **Data flow**: If you use a local backend (Ollama/LM Studio), **no data leaves your machine**. If you use a remote fallback, specs and injected context files are sent to that API.
+- **Safety**: `journeyman` performs atomic writes. If a file exists, it automatically creates a `.bak` copy before overwriting.
+
+## Exit Codes
+
+Agents rely on strict exit codes to manage the workflow:
+
+| Code | Meaning | Agent Action |
+|---|---|---|
+| **0** | Success — validated output written | Review the output |
+| **1** | No code block in response | Tighten spec and retry |
+| **2** | Config, argument, or network error | Do NOT retry; ask user to check setup |
+| **3** | Validation failed after max retries | Fix the file directly |
+| **4** | Stream interrupted | Retry |
+| **5** | `--expect` pattern missing after retries | Tighten expect/signatures; retry |
+
+---
+*License: MIT*