ai-rail 0.1.0a7__tar.gz

ai_rail-0.1.0a7/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+
+# Editors / OS
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Local env
+.env
+.env.*

ai_rail-0.1.0a7/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+Maintained by Afshin Saberi.
+
+## 0.1.0a7
+
+- Made `rail init --force` safer when refreshing initialized repositories.
+- Added `rail upgrade` to safely refresh repo-local AI Rail runtime/template files.
+- Switched git path parsing to robust `porcelain -z` handling.
+- Cleaned up cross-platform CI and documentation readiness.
+- Added author/about metadata to public CLI output.
+- Finished packaging readiness fixes for the alpha release.
+
+## 0.1.0a6
+
+- Added `rail demo` to print a copyable public demo walkthrough.
+- Added `rail release-check` to validate public-alpha packaging and docs readiness.
+- Added `docs/QUICKSTART.md`, `docs/COMMANDS.md`, and `docs/RELEASE.md`.
+- Added `examples/demo-todo/DEMO_SCRIPT.md` and updated the demo README.
+- Added a package test workflow under `.github/workflows/tests.yml`.
+- Updated README and install docs for the final public-alpha workflow.
+- Made repo detection during `rail init` prefer fast local git remote detection before falling back to `gh`.
+
+## 0.1.0a5
+
+- Added `rail export` to generate tool-specific context files from the AI Rail project brain.
+- Added exports for root `AGENTS.md`, root `CLAUDE.md`, root `AIDER.md`, `.cursor/rules/ai-rail.mdc`, and `.github/copilot-instructions.md`.
+- Added safe managed-block updates using `AI_RAIL_EXPORT` markers.
+- Refuse to overwrite existing unmarked human files unless `--force` is used, with `.rail.bak` backups.
+- Added `--target`, `--dry-run`, `--force`, `--no-snapshot`, and `--max-history` options for exports.
+- Updated tests and docs for the one-project-brain/many-tool-files workflow.
+
+## 0.1.0a4
+
+- Added `rail snapshot` to generate a portable project brain under `.rail/brain/`.
+- Added `rail handoff` to create paste-ready model-specific handoffs for ChatGPT, Codex, Claude, Cursor, Aider, or generic AI sessions.
+- Added optional handoff inclusion for last review pack and last checks output.
+- Saved handoff outputs under `.rail/state/last-handoff-*.md`.
+- Updated docs and tests for the portable project brain workflow.
+
+## 0.1.0a3
+
+- Added commit/ship safety preflight requiring a fresh review pack and passed fresh checks by default.
+- Added dangerous/generated path guard for `.env`, keys, local databases, build outputs, dependencies, caches, and `.rail/state/`.
+- Changed commit staging to stage known changed paths instead of blindly staging the whole repository.
+- Added small untracked text file contents to review packs so new files are visible during AI audit.
+- Added first-push upstream handling with `git push -u origin HEAD` when needed.
+- Added `--allow-missing-checks` and `--allow-stale` escape hatches for advanced users.
+- Fixed legacy `mode=issue` active-state handling in the public wrapper.
+- Aligned the embedded repo-local runtime version with the public alpha version after audit.
+- Added Phase 3 regression tests for safety preflight, dangerous files, fresh review/check commit flow, and untracked review contents.
+
+## 0.1.0a2
+
+- Added short daily commands: `rail next`, `rail verify`, `rail ship`, and `rail resume`.
+- Updated README/docs/demo templates to lead with the shorter daily workflow.
+- Kept detailed legacy workflow commands available for manual control.
+
+## 0.1.0a1
+
+- Renamed project from AI Rail predecessor naming to `AI Rail`.
+- Renamed install package to `ai-rail`.
+- Renamed CLI entrypoint to `rail`.
+- Renamed project state folder to `.rail/`.
+- Renamed repo-local runtime file to `.rail/rail.py`.
+- Updated docs, examples, templates, tests, and package metadata for the rename.

ai_rail-0.1.0a7/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Project goals:
+
+- keep AI Rail local-first
+- keep the CLI small
+- keep GitHub Issues as the task database
+- keep AI workflows explicit and auditable
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Tests
+
+Run the full test suite:
+
+```bash
+python -m pytest -q
+```
+
+Also run the basic CLI checks:
+
+```bash
+python -m py_compile src/ai_rail/cli.py
+python -m ai_rail --version
+```
+
+## Before opening a PR
+
+```bash
+python -m pytest -q
+python -m py_compile src/ai_rail/cli.py
+```

ai_rail-0.1.0a7/LICENSE

@@ -0,0 +1,203 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+Copyright 2026 Afshin Saberi
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative
+Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!) The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+   Copyright 2026 Afshin Saberi
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ai_rail-0.1.0a7/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: ai-rail
+Version: 0.1.0a7
+Summary: A local-first workflow rail and portable project brain for AI-assisted development.
+Project-URL: Homepage, https://theafshin.com
+Project-URL: Repository, https://github.com/afshinsb/ai-rail
+Project-URL: Documentation, https://github.com/afshinsb/ai-rail/tree/main/docs
+Author: Afshin Saberi
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai,chatgpt,claude,cli,codex,cursor,developer-tools,github,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AI Rail
+
+[![Tests](https://github.com/afshinsb/ai-rail/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/afshinsb/ai-rail/actions/workflows/tests.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](docs/RELEASE.md)
+
+**Never explain your project twice to AI.**
+
+AI Rail is a local-first CLI that keeps AI-assisted development focused, repeatable, and safe.
+
+It gives every Git repo a portable project brain, a simple daily workflow, and scoped prompts for tools like ChatGPT, Codex, Claude, Cursor, and Aider - so you can move between AI tools without re-explaining the codebase, losing context, or letting the coding agent drift into unrelated files.
+
+```text
+rail n  -> start the next scoped task
+rail v  -> review, run local checks, and create an audit prompt
+rail s  -> safely commit, push, close, and sync
+rail h  -> continue in a new AI chat with full project context
+```
+
+AI Rail keeps the coding agent on the active issue, keeps ChatGPT in the review loop, and lets your own machine run the tests - saving tokens, reducing over-coding, and making AI development feel controlled instead of chaotic.
+
+<p align="center">
+  <img src="docs/assets/ai-rail.png" alt="AI Rail overview" width="900">
+</p>
+
+## Who This Is For
+
+AI Rail is for developers who:
+
+- use more than one AI coding tool on the same repo
+- want GitHub Issues to be the task source of truth
+- want repeatable prompts, review packs, checks, and handoffs
+- prefer local-first tooling over hosted workflow state
+- work solo or in small repos where conservative commit safety matters
+
+## What AI Rail Is Not
+
+AI Rail is not:
+
+- an AI model, agent runtime, or hosted service
+- a replacement for Git, GitHub Issues, or your test suite
+- a project management system for large teams
+- a tool that sends code to a remote service by itself
+- a way to bypass review, checks, or secret-file safety
+
+## Install
+
+AI Rail is currently alpha software.
+
+Recommended public install:
+
+```bash
+pipx install ai-rail
+rail --version
+```
+
+Latest source from GitHub:
+
+```bash
+pipx install git+https://github.com/afshinsb/ai-rail.git
+rail --version
+```
+
+Contributor install from this source checkout:
+
+```bash
+pip install -e ".[dev]"
+rail --version
+```
+
+## Quick Demo
+
+Print the built-in walkthrough:
+
+```bash
+rail demo
+```
+
+Try the bundled demo app:
+
+```bash
+cd examples/demo-todo
+rail init --stack node --project-name "AI Rail Demo TODO"
+rail doctor
+npm run check
+gh issue create --title "Add todo body validation" --body-file issues/001-add-body-validation.md
+rail next --copy
+```
+
+## 60-Second Quickstart
+
+Inside any Git repo:
+
+```bash
+rail init --stack node --project-name "My Project"
+rail doctor
+rail resume
+```
+
+Daily loop:
+
+```bash
+rail next --copy
+# paste/run the generated prompt in your AI coding tool
+rail verify --copy
+# paste the generated review prompt into ChatGPT/Claude for audit
+rail ship "type(scope): message"
+```
+
+Short alias loop:
+
+```bash
+rail n
+# paste/run the generated prompt in your AI coding tool
+rail v
+# paste the generated review prompt into ChatGPT/Claude for audit
+rail s "type(scope): message"
+```
+
+When switching AI tools or opening a new chat:
+
+```bash
+rail snapshot
+rail handoff --for chatgpt --include-review --include-checks --copy
+```
+
+To update tool-specific AI instruction files from the same project brain:
+
+```bash
+rail export
+```
+
+## Core Commands
+
+| Command | Purpose |
+|---|---|
+| `rail init` | Add AI Rail files to a repo |
+| `rail resume` | Show where you stopped |
+| `rail next` | Start the next issue and generate the first prompt |
+| `rail handoff` | Generate portable context for another AI session/model |
+| `rail verify` | Capture review info, run checks, and generate an audit prompt |
+| `rail ship` | Commit, push, close the issue, mark done, and sync |
+| `rail snapshot` | Refresh `.rail/brain/` project-brain files |
+| `rail export` | Generate `AGENTS.md`, `CLAUDE.md`, Cursor rules, `AIDER.md`, and Copilot instructions |
+| `rail demo` | Print the public demo script |
+| `rail release-check` | Check packaging/docs readiness |
+
+Common aliases are thin wrappers over the long commands: `rail r` for `resume`, `rail n` for `next --copy`, `rail v` for `verify --copy`, `rail s` for `ship`, `rail snap` for `snapshot`, `rail h`/`hc`/`hg`/`hl` for handoffs, `rail x`/`xd`/`xf` for exports, and `rail rc` for `release-check`.
+
+Detailed commands such as `rail start`, `rail prompt`, `rail review`, `rail checks`, `rail commit`, `rail issue-close`, `rail done`, and `rail sync` remain available for manual control.
+
+## Portable Project Brain
+
+`rail snapshot` writes:
+
+```text
+.rail/brain/PROJECT.md
+.rail/brain/CURRENT_TASK.md
+.rail/brain/STATUS.md
+.rail/brain/RECENT_HISTORY.md
+.rail/brain/HANDOFF.md
+```
+
+`rail handoff --for codex|chatgpt|claude|cursor|aider --copy` turns that brain into a paste-ready handoff so a new AI session can continue from the current project state.
+
+## Tool-Specific Exports
+
+`rail export` turns the single AI Rail project brain into files that different AI coding tools already know how to read:
+
+```text
+AGENTS.md
+CLAUDE.md
+AIDER.md
+.cursor/rules/ai-rail.mdc
+.github/copilot-instructions.md
+```
+
+Exports are safe by default. AI Rail updates its own managed block when markers are present, but refuses to overwrite existing human files unless you pass `--force`, which first writes a `.rail.bak` backup.
+
+## Safety Defaults
+
+`rail ship` refuses unsafe commits by default when:
+
+- the review pack is missing or stale
+- checks are missing, failed, or stale
+- dangerous/generated files such as `.env`, keys, local databases, `node_modules/`, `dist/`, or `.rail/state/` are changed
+
+Escape hatches exist for advanced users, but the normal path is intentionally conservative.
+
+## Local-First Privacy
+
+AI Rail does not send your code anywhere by itself. It shells out to `git`, `gh`, and your configured local checks.
+
+By default, `.rail/state/history.jsonl` is ignored by git to avoid committing personal workflow history into team repos.
+
+License: Apache License 2.0.
+
+## Author
+
+- Afshin Saberi
+- GitHub: https://github.com/afshinsb
+- Website: https://theafshin.com
+
+## Docs
+
+- [Quickstart](docs/QUICKSTART.md)
+- [Install](docs/INSTALL.md)
+- [Commands](docs/COMMANDS.md)
+- [Workflows](docs/WORKFLOWS.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Release checklist](docs/RELEASE.md)
+- [Roadmap](docs/ROADMAP.md)