workrail 0.1.0__tar.gz

workrail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xusheng
+
+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.

workrail-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: workrail
+Version: 0.1.0
+Summary: A local-first workstream journal for developers and AI coding agents.
+Author: xusheng
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xu-sheng-dev/workrail
+Project-URL: Repository, https://github.com/xu-sheng-dev/workrail.git
+Project-URL: Issues, https://github.com/xu-sheng-dev/workrail/issues
+Keywords: developer-tools,journal,cli,sqlite,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# WorkRail
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Status](https://img.shields.io/badge/status-alpha-orange)
+
+WorkRail is a local-first workstream journal for developers and AI coding agents.
+
+It records the useful trail around meaningful work: what started, what changed, what got
+blocked, what should happen next, and how the work finished. WorkRail is intentionally
+smaller than a task board. It stores structured progress events in a local SQLite database,
+then turns them into reports, JSON state, and a read-only dashboard.
+
+## Why WorkRail
+
+- Keep a compact timeline for work that spans more than one command or message.
+- Let AI coding agents leave useful progress notes without dumping full transcripts.
+- Generate daily and weekly Markdown reports from structured events.
+- Inspect the current workstream from scripts with JSON output.
+- Keep data local by default, with no service account or hosted backend required.
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install workrail
+```
+
+If the package has not been published yet, install from a local checkout:
+
+```bash
+pip install -e .
+```
+
+Or install directly from GitHub:
+
+```bash
+python -m pip install "git+https://github.com/xu-sheng-dev/workrail.git"
+```
+
+For development:
+
+```bash
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+```
+
+On macOS or Linux:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+WorkRail has no runtime dependencies outside the Python standard library.
+
+## Quick Start
+
+```bash
+workrail start "Fix token expiry handling"
+workrail checkpoint "Found a timestamp unit mismatch"
+workrail note "Backend returns seconds while frontend expects milliseconds"
+workrail next "Verify with local mock data"
+workrail done "Fixed the conversion and passed related tests"
+workrail report today
+```
+
+WorkRail keeps one current rail. If another rail is already active, `start` fails by
+default so you do not accidentally mix two workstreams. Finish it, abandon it, or
+intentionally replace it:
+
+```bash
+workrail abandon "No longer current"
+workrail start "New task" --force
+```
+
+Use `--help` to inspect the CLI:
+
+```bash
+workrail --help
+workrail start --help
+```
+
+## Agent Usage
+
+WorkRail is designed to be easy for coding agents to use while they work.
+
+```bash
+workrail current --json
+workrail start "Improve test coverage" --source agent --project auto --quiet
+workrail checkpoint "Added storage regression tests" --source agent --quiet
+workrail done "Implemented tests and verified with pytest" --source agent --quiet
+```
+
+The bundled skill gives agents a small policy for when to log progress, when to record a
+blocker, and when to stop. Install it into a supported agent skills directory:
+
+```bash
+workrail install-skill --agent codex
+workrail install-skill --agent claude
+workrail install-skill --agent opencode
+```
+
+You can also install to a custom directory:
+
+```bash
+workrail install-skill --target ./installed-skills --force
+```
+
+With `--agent auto`, WorkRail installs into the only existing supported agent directory.
+If multiple supported directories exist, specify `--agent` or `--target`.
+
+## Local Dashboard
+
+Start the read-only dashboard:
+
+```bash
+workrail web
+```
+
+Open:
+
+```text
+http://127.0.0.1:18765
+```
+
+The dashboard binds to `127.0.0.1` by default. Binding to another host can expose local
+work data on your network.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `start` | Start a new rail. |
+| `note` or `n` | Record a note on the current rail. |
+| `checkpoint` | Record meaningful progress. |
+| `block` | Mark the current rail as blocked and record why. |
+| `next` | Record the next step. |
+| `done` | Complete the current rail. |
+| `abandon` | Stop tracking the current rail without marking it done. |
+| `current` | Show the current rail, optionally as JSON. |
+| `today` | Show today's workstream. |
+| `report` | Generate a Markdown report for `today` or `week`. |
+| `web` | Start the local dashboard. |
+| `install-skill` | Install the bundled agent skill. |
+
+## Data And Privacy
+
+WorkRail stores data in a local SQLite database. Set `WORKRAIL_DB` to choose the database
+file:
+
+```bash
+set WORKRAIL_DB=C:\temp\workrail.db
+```
+
+On macOS or Linux:
+
+```bash
+export WORKRAIL_DB=/tmp/workrail.db
+```
+
+Without `WORKRAIL_DB`, WorkRail uses the standard local app data directory:
+
+| Platform | Default location |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%\WorkRail\workrail.db` |
+| macOS | `~/Library/Application Support/workrail/workrail.db` |
+| Linux | `$XDG_DATA_HOME/workrail/workrail.db` or `~/.local/share/workrail/workrail.db` |
+
+WorkRail includes basic safeguards that reject common secret-shaped content such as token
+assignments, bearer tokens, private keys, and AWS access keys. Treat this as a guardrail,
+not a substitute for reviewing what you ask humans or agents to record.
+
+## Project Status
+
+WorkRail is alpha software. The first release focuses on a small, stable core:
+
+- Local SQLite storage.
+- A compact CLI.
+- Agent-friendly JSON output.
+- Daily and weekly Markdown reports.
+- A read-only local dashboard.
+- A bundled agent skill and installer command.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+```
+
+## License
+
+WorkRail is released under the MIT License. See `LICENSE`.

workrail-0.1.0/README.md

@@ -0,0 +1,199 @@
+# WorkRail
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Status](https://img.shields.io/badge/status-alpha-orange)
+
+WorkRail is a local-first workstream journal for developers and AI coding agents.
+
+It records the useful trail around meaningful work: what started, what changed, what got
+blocked, what should happen next, and how the work finished. WorkRail is intentionally
+smaller than a task board. It stores structured progress events in a local SQLite database,
+then turns them into reports, JSON state, and a read-only dashboard.
+
+## Why WorkRail
+
+- Keep a compact timeline for work that spans more than one command or message.
+- Let AI coding agents leave useful progress notes without dumping full transcripts.
+- Generate daily and weekly Markdown reports from structured events.
+- Inspect the current workstream from scripts with JSON output.
+- Keep data local by default, with no service account or hosted backend required.
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install workrail
+```
+
+If the package has not been published yet, install from a local checkout:
+
+```bash
+pip install -e .
+```
+
+Or install directly from GitHub:
+
+```bash
+python -m pip install "git+https://github.com/xu-sheng-dev/workrail.git"
+```
+
+For development:
+
+```bash
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+```
+
+On macOS or Linux:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+WorkRail has no runtime dependencies outside the Python standard library.
+
+## Quick Start
+
+```bash
+workrail start "Fix token expiry handling"
+workrail checkpoint "Found a timestamp unit mismatch"
+workrail note "Backend returns seconds while frontend expects milliseconds"
+workrail next "Verify with local mock data"
+workrail done "Fixed the conversion and passed related tests"
+workrail report today
+```
+
+WorkRail keeps one current rail. If another rail is already active, `start` fails by
+default so you do not accidentally mix two workstreams. Finish it, abandon it, or
+intentionally replace it:
+
+```bash
+workrail abandon "No longer current"
+workrail start "New task" --force
+```
+
+Use `--help` to inspect the CLI:
+
+```bash
+workrail --help
+workrail start --help
+```
+
+## Agent Usage
+
+WorkRail is designed to be easy for coding agents to use while they work.
+
+```bash
+workrail current --json
+workrail start "Improve test coverage" --source agent --project auto --quiet
+workrail checkpoint "Added storage regression tests" --source agent --quiet
+workrail done "Implemented tests and verified with pytest" --source agent --quiet
+```
+
+The bundled skill gives agents a small policy for when to log progress, when to record a
+blocker, and when to stop. Install it into a supported agent skills directory:
+
+```bash
+workrail install-skill --agent codex
+workrail install-skill --agent claude
+workrail install-skill --agent opencode
+```
+
+You can also install to a custom directory:
+
+```bash
+workrail install-skill --target ./installed-skills --force
+```
+
+With `--agent auto`, WorkRail installs into the only existing supported agent directory.
+If multiple supported directories exist, specify `--agent` or `--target`.
+
+## Local Dashboard
+
+Start the read-only dashboard:
+
+```bash
+workrail web
+```
+
+Open:
+
+```text
+http://127.0.0.1:18765
+```
+
+The dashboard binds to `127.0.0.1` by default. Binding to another host can expose local
+work data on your network.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `start` | Start a new rail. |
+| `note` or `n` | Record a note on the current rail. |
+| `checkpoint` | Record meaningful progress. |
+| `block` | Mark the current rail as blocked and record why. |
+| `next` | Record the next step. |
+| `done` | Complete the current rail. |
+| `abandon` | Stop tracking the current rail without marking it done. |
+| `current` | Show the current rail, optionally as JSON. |
+| `today` | Show today's workstream. |
+| `report` | Generate a Markdown report for `today` or `week`. |
+| `web` | Start the local dashboard. |
+| `install-skill` | Install the bundled agent skill. |
+
+## Data And Privacy
+
+WorkRail stores data in a local SQLite database. Set `WORKRAIL_DB` to choose the database
+file:
+
+```bash
+set WORKRAIL_DB=C:\temp\workrail.db
+```
+
+On macOS or Linux:
+
+```bash
+export WORKRAIL_DB=/tmp/workrail.db
+```
+
+Without `WORKRAIL_DB`, WorkRail uses the standard local app data directory:
+
+| Platform | Default location |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%\WorkRail\workrail.db` |
+| macOS | `~/Library/Application Support/workrail/workrail.db` |
+| Linux | `$XDG_DATA_HOME/workrail/workrail.db` or `~/.local/share/workrail/workrail.db` |
+
+WorkRail includes basic safeguards that reject common secret-shaped content such as token
+assignments, bearer tokens, private keys, and AWS access keys. Treat this as a guardrail,
+not a substitute for reviewing what you ask humans or agents to record.
+
+## Project Status
+
+WorkRail is alpha software. The first release focuses on a small, stable core:
+
+- Local SQLite storage.
+- A compact CLI.
+- Agent-friendly JSON output.
+- Daily and weekly Markdown reports.
+- A read-only local dashboard.
+- A bundled agent skill and installer command.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+```
+
+## License
+
+WorkRail is released under the MIT License. See `LICENSE`.

workrail-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "workrail"
+version = "0.1.0"
+description = "A local-first workstream journal for developers and AI coding agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "xusheng" }
+]
+keywords = ["developer-tools", "journal", "cli", "sqlite", "agent"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/xu-sheng-dev/workrail"
+Repository = "https://github.com/xu-sheng-dev/workrail.git"
+Issues = "https://github.com/xu-sheng-dev/workrail/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build",
+  "pytest",
+  "ruff",
+]
+
+[project.scripts]
+workrail = "workrail.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+workrail = ["skills/workrail-agent/SKILL.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

workrail-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

workrail-0.1.0/src/workrail/__init__.py

@@ -0,0 +1,3 @@
+"""WorkRail package."""
+
+__version__ = "0.1.0"

workrail-0.1.0/src/workrail/__main__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import sys
+
+from workrail.cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())