promptmigrate-cli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. promptmigrate_cli-0.1.0/LICENSE +21 -0
  2. promptmigrate_cli-0.1.0/PKG-INFO +247 -0
  3. promptmigrate_cli-0.1.0/README.md +223 -0
  4. promptmigrate_cli-0.1.0/pyproject.toml +54 -0
  5. promptmigrate_cli-0.1.0/setup.cfg +4 -0
  6. promptmigrate_cli-0.1.0/src/promptmigrate/__init__.py +21 -0
  7. promptmigrate_cli-0.1.0/src/promptmigrate/__main__.py +3 -0
  8. promptmigrate_cli-0.1.0/src/promptmigrate/apply.py +116 -0
  9. promptmigrate_cli-0.1.0/src/promptmigrate/cli.py +123 -0
  10. promptmigrate_cli-0.1.0/src/promptmigrate/commands/__init__.py +5 -0
  11. promptmigrate_cli-0.1.0/src/promptmigrate/commands/check.py +65 -0
  12. promptmigrate_cli-0.1.0/src/promptmigrate/commands/current.py +25 -0
  13. promptmigrate_cli-0.1.0/src/promptmigrate/commands/diff.py +19 -0
  14. promptmigrate_cli-0.1.0/src/promptmigrate/commands/downgrade.py +36 -0
  15. promptmigrate_cli-0.1.0/src/promptmigrate/commands/env.py +35 -0
  16. promptmigrate_cli-0.1.0/src/promptmigrate/commands/get.py +48 -0
  17. promptmigrate_cli-0.1.0/src/promptmigrate/commands/history.py +41 -0
  18. promptmigrate_cli-0.1.0/src/promptmigrate/commands/init.py +43 -0
  19. promptmigrate_cli-0.1.0/src/promptmigrate/commands/plan.py +51 -0
  20. promptmigrate_cli-0.1.0/src/promptmigrate/commands/restamp.py +47 -0
  21. promptmigrate_cli-0.1.0/src/promptmigrate/commands/revision.py +97 -0
  22. promptmigrate_cli-0.1.0/src/promptmigrate/commands/upgrade.py +36 -0
  23. promptmigrate_cli-0.1.0/src/promptmigrate/commands/validate.py +96 -0
  24. promptmigrate_cli-0.1.0/src/promptmigrate/core.py +30 -0
  25. promptmigrate_cli-0.1.0/src/promptmigrate/draftdiff.py +41 -0
  26. promptmigrate_cli-0.1.0/src/promptmigrate/errors.py +91 -0
  27. promptmigrate_cli-0.1.0/src/promptmigrate/output.py +122 -0
  28. promptmigrate_cli-0.1.0/src/promptmigrate/plan.py +112 -0
  29. promptmigrate_cli-0.1.0/src/promptmigrate/project.py +160 -0
  30. promptmigrate_cli-0.1.0/src/promptmigrate/protocol/__init__.py +9 -0
  31. promptmigrate_cli-0.1.0/src/promptmigrate/protocol/equality.py +15 -0
  32. promptmigrate_cli-0.1.0/src/promptmigrate/protocol/jsonloader.py +92 -0
  33. promptmigrate_cli-0.1.0/src/promptmigrate/protocol/limits.py +9 -0
  34. promptmigrate_cli-0.1.0/src/promptmigrate/protocol/rules.py +80 -0
  35. promptmigrate_cli-0.1.0/src/promptmigrate/revisions.py +181 -0
  36. promptmigrate_cli-0.1.0/src/promptmigrate/secretscan.py +195 -0
  37. promptmigrate_cli-0.1.0/src/promptmigrate/store/__init__.py +13 -0
  38. promptmigrate_cli-0.1.0/src/promptmigrate/store/environments.py +181 -0
  39. promptmigrate_cli-0.1.0/src/promptmigrate/store/events.py +70 -0
  40. promptmigrate_cli-0.1.0/src/promptmigrate/store/lock.py +66 -0
  41. promptmigrate_cli-0.1.0/src/promptmigrate/store/sqlite.py +147 -0
  42. promptmigrate_cli-0.1.0/src/promptmigrate_cli.egg-info/PKG-INFO +247 -0
  43. promptmigrate_cli-0.1.0/src/promptmigrate_cli.egg-info/SOURCES.txt +46 -0
  44. promptmigrate_cli-0.1.0/src/promptmigrate_cli.egg-info/dependency_links.txt +1 -0
  45. promptmigrate_cli-0.1.0/src/promptmigrate_cli.egg-info/entry_points.txt +2 -0
  46. promptmigrate_cli-0.1.0/src/promptmigrate_cli.egg-info/requires.txt +6 -0
  47. promptmigrate_cli-0.1.0/src/promptmigrate_cli.egg-info/top_level.txt +1 -0
  48. promptmigrate_cli-0.1.0/tests/test_core.py +120 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Himanshu Kumar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,247 @@
1
+ Metadata-Version: 2.4
2
+ Name: promptmigrate-cli
3
+ Version: 0.1.0
4
+ Summary: Alembic-inspired migration control for production AI prompts and agent configurations
5
+ Author: Himanshu Kumar
6
+ License: MIT
7
+ Keywords: llm,prompt,migration,version-control,agents
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Topic :: Software Development :: Version Control
15
+ Requires-Python: >=3.10
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Provides-Extra: dev
19
+ Requires-Dist: pytest>=8; extra == "dev"
20
+ Requires-Dist: hypothesis>=6; extra == "dev"
21
+ Requires-Dist: pytest-cov>=5; extra == "dev"
22
+ Requires-Dist: mypy<2.5,>=2.4; extra == "dev"
23
+ Dynamic: license-file
24
+
25
+ <p align="center">
26
+ <img src="assets/readme-banner.svg" alt="PromptMigrate — Alembic-style migrations for LLM prompts and AI agents" width="100%" />
27
+ </p>
28
+
29
+ <p align="center">
30
+ <a href="https://github.com/himanshu231204/prompt-migrate/actions/workflows/ci.yml"><img src="https://github.com/himanshu231204/prompt-migrate/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
31
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
32
+ <img src="https://img.shields.io/badge/python-3.10%2B-3776ab.svg?logo=python&logoColor=white" alt="Python 3.10+" />
33
+ <img src="https://img.shields.io/badge/runtime_deps-0_(stdlib_only)-2ea44f.svg" alt="Zero runtime dependencies" />
34
+ <a href="https://github.com/himanshu231204/prompt-migrate/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"><img src="https://img.shields.io/github/issues/himanshu231204/prompt-migrate/good%20first%20issue?color=7057ff&label=good%20first%20issues" alt="Good first issues" /></a>
35
+ </p>
36
+
37
+ # PromptMigrate
38
+
39
+ **Alembic-style migrations for LLM prompts and AI agent configuration.** Keep prompts and agent configs as Git-tracked JSON, generate ordered, reviewable revisions, apply them to environments, roll them back, and fail CI when an environment drifts from history.
40
+
41
+ > [!NOTE]
42
+ > PromptMigrate is a **v0.1 local prototype**. Environments are local SQLite files, and nothing is deployed to Langfuse, OpenAI, Azure AI Foundry or any other runtime. See [what is and isn't guaranteed](#safety-and-integrity).
43
+
44
+ ## Why PromptMigrate?
45
+
46
+ Langfuse, MLflow, Agenta and promptctl already version and manage prompts. PromptMigrate focuses on something narrower: an **ordered migration protocol** for configuration, the way Alembic does it for database schemas.
47
+
48
+ - **Ordered history:** every revision names its predecessor, forming one linear chain.
49
+ - **Reversible:** each revision stores full before/after snapshots, so `downgrade` is deterministic.
50
+ - **Integrity-checked:** applied revisions are checksummed; editing one, or changing an environment by hand, is reported as drift.
51
+ - **CI-friendly:** stable exit codes and `--output json`.
52
+ - **Declarative and safe:** revisions are pure JSON, never executable code. The runtime uses only the Python standard library.
53
+
54
+ It's designed to sit alongside prompt registries, not replace them.
55
+
56
+ ## Install
57
+
58
+ Python 3.10 or newer. The PyPI distribution is named `promptmigrate-cli` (the name `promptmigrate` was already taken); the command and the import are both `promptmigrate`:
59
+
60
+ ```bash
61
+ python -m pip install promptmigrate-cli
62
+ promptmigrate --version
63
+ ```
64
+
65
+ To work on PromptMigrate itself, install from a clone instead:
66
+
67
+ ```bash
68
+ git clone https://github.com/himanshu231204/prompt-migrate.git
69
+ cd prompt-migrate
70
+ python -m pip install -e .
71
+ ```
72
+
73
+ ## Five-minute example
74
+
75
+ In a separate, empty project directory, run the example with the starter draft
76
+ that `init` creates. You can edit the draft before generating the first revision.
77
+
78
+ <!-- quickstart-smoke:start -->
79
+ ```bash
80
+ promptmigrate init
81
+ promptmigrate env list
82
+ promptmigrate env add qa
83
+ # Optional: edit .promptmigrate/drafts/assistant.json with the desired system prompt,
84
+ # model, temperature, tool specs, response schema, etc.
85
+ promptmigrate revision -m "initial assistant prompt"
86
+ promptmigrate history
87
+ promptmigrate plan --env dev --target head
88
+ promptmigrate upgrade head --env dev
89
+ promptmigrate check --env dev --require-head
90
+ promptmigrate get assistant --env dev
91
+ ```
92
+ <!-- quickstart-smoke:end -->
93
+
94
+ Then edit `.promptmigrate/drafts/assistant.json` and run:
95
+
96
+ ```bash
97
+ promptmigrate diff
98
+ promptmigrate revision -m "strengthen refusal instructions"
99
+ promptmigrate upgrade head --env staging
100
+ promptmigrate current --env staging
101
+ promptmigrate downgrade -1 --env staging
102
+ ```
103
+
104
+ A revision describes the change from the previous Git-tracked revision, **not from your local dev database**, so pull your team's latest revisions before generating one. For multi-agent systems, add more drafts such as `planner.json` or `reviewer.json`. Deleting a draft and generating a revision deletes that config in the target environment, reversibly.
105
+
106
+ A runnable two-agent walkthrough is in [`examples/multi-agent-basic/`](examples/multi-agent-basic/).
107
+
108
+ ## What a revision looks like
109
+
110
+ ```json
111
+ {
112
+ "format_version": 1,
113
+ "revision": "0123456789ab",
114
+ "down_revision": null,
115
+ "message": "initial assistant",
116
+ "created_at": "2026-10-29T00:00:00+00:00",
117
+ "changes": {
118
+ "assistant": {
119
+ "before": null,
120
+ "after": {
121
+ "messages": [{"role": "system", "content": "You are helpful."}],
122
+ "model": "provider/model-id",
123
+ "parameters": {"temperature": 0}
124
+ }
125
+ }
126
+ }
127
+ }
128
+ ```
129
+
130
+ `before` and `after` are full JSON snapshots, and `null` means the config is absent. One revision can change several configs in a single atomic transaction. Snapshots make reversal deterministic, at the cost of larger files and keeping old values in Git history.
131
+
132
+ ## How it works
133
+
134
+ ```mermaid
135
+ flowchart LR
136
+ D["drafts/*.json<br/>desired config"] -- "revision -m" --> V["versions/*.json<br/>ordered revisions (Git)"]
137
+ V -- "upgrade / downgrade" --> S[("states/#lt;env#gt;.sqlite3<br/>config + applied ledger")]
138
+ V -. "check: ledger and config<br/>must match history" .-> S
139
+ ```
140
+
141
+ `upgrade` and `downgrade` verify the environment against history, then change the configs and the applied-revision ledger together in one SQLite transaction. If anything doesn't match, the command fails without writing.
142
+
143
+ ## Commands
144
+
145
+ | Command | Behavior |
146
+ |---|---|
147
+ | `init` | Create the migration workspace and a starter draft |
148
+ | `diff` | Compare local drafts with the latest revision |
149
+ | `revision -m "..."` | Generate a revision from draft changes |
150
+ | `history` | Print the revision chain |
151
+ | `current --env dev` | Show an environment's current revision |
152
+ | `plan --env dev [--target head]` | Preview what an upgrade or downgrade would change; writes nothing |
153
+ | `upgrade head --env dev` | Apply pending revisions atomically |
154
+ | `downgrade -1 --env dev` | Undo the last applied revision (`base` reverts all) |
155
+ | `check --env dev --require-head` | Detect drift, edited applied revisions and pending revisions |
156
+ | `restamp --env dev` | Accept applied v0 revisions whose files changed only in line endings |
157
+ | `validate [--strict] [--drafts-clean]` | Check revision history, drafts and manifests without touching any environment |
158
+ | `get assistant --env dev` | Read a config from a local environment |
159
+ | `env add qa` / `env list` | Declare and list local environments |
160
+
161
+ Global flags: `--project <dir>` targets another project directory, and `--output json` prints machine-readable results. Exit codes are documented in [`docs/CLI_SPEC.md`](docs/CLI_SPEC.md).
162
+
163
+ ## Project layout
164
+
165
+ ```text
166
+ project/
167
+ .promptmigrate/
168
+ drafts/ # desired JSON configs (Git tracked)
169
+ versions/ # revisions with before/after snapshots (Git tracked)
170
+ environments.json # declared environments (Git tracked)
171
+ states/ # local SQLite state per environment (gitignored)
172
+ ```
173
+
174
+ > [!WARNING]
175
+ > `states/prod.sqlite3` is a **local file named prod**, not a production deployment. Production-like names print a warning for this reason.
176
+
177
+ ## Use in CI
178
+
179
+ In your project's workflow, install PromptMigrate from its repository, then replay every revision into a throwaway environment and verify it:
180
+
181
+ ```yaml
182
+ - run: python -m pip install "git+https://github.com/himanshu231204/prompt-migrate.git"
183
+ - run: promptmigrate validate --strict --drafts-clean
184
+ - run: promptmigrate upgrade head --env dev
185
+ - run: promptmigrate check --env dev --require-head
186
+ ```
187
+
188
+ `states/` is gitignored, so a fresh CI checkout starts every environment at the empty base. This job proves the revision history loads, applies cleanly in order from scratch, and verifies. It can't check a long-lived environment such as `staging`, because that state lives only on the machine that owns it; shared remote state is planned for Phase 3.
189
+
190
+ `validate` checks only the files in Git (history, drafts, manifests, secret allowlist) and exits 3 on any finding under `--strict`; `--drafts-clean` also fails when a draft edit has no revision yet. `check` exits non-zero on drift, an edited applied revision, or (with `--require-head`) pending revisions. It verifies **integrity, not prompt quality**: it doesn't measure answer quality or prompt-injection resistance.
191
+
192
+ ## Safety and integrity
193
+
194
+ **Guaranteed today:**
195
+
196
+ - Applying or reverting several revisions is atomic **inside one local SQLite database**.
197
+ - Applied revisions are checksummed. Editing one blocks that environment (v1 revisions ignore formatting-only changes).
198
+ - Out-of-band changes to an environment's configs are rejected as drift.
199
+ - History is one linear chain; parallel branches must be resolved first.
200
+ - Revisions are pure JSON; no migration code is ever executed.
201
+ - No provider API keys or network calls are needed.
202
+ - Secret-like values are refused in new revisions and redacted in `diff`/`get` output. Detection is heuristic, and secrets already in Git must be rotated.
203
+
204
+ **Not guaranteed yet:** transactions across model providers, locks across hosts, remote state, signed revisions, authentication, evaluation gates, canary releases or an append-only audit history. Don't use v0.1 to manage live production prompts or secrets.
205
+
206
+ ## Roadmap
207
+
208
+ The plan is in [`docs/ROADMAP.md`](docs/ROADMAP.md) and tracked as GitHub milestones:
209
+
210
+ 1. [**Phase 1: Harden the migration core**](https://github.com/himanshu231204/prompt-migrate/milestone/1) (in progress): concurrency and fault-injection tests, package smoke tests.
211
+ 2. [**Phase 2: Evaluation and policy gates**](https://github.com/himanshu231204/prompt-migrate/milestone/2)
212
+ 3. [**Phase 3: Production release protocol**](https://github.com/himanshu231204/prompt-migrate/milestone/3)
213
+ 4. [**Phase 4: Stable community release**](https://github.com/himanshu231204/prompt-migrate/milestone/4)
214
+
215
+ ## Contributing
216
+
217
+ Contributions are welcome. Every issue is a single task with acceptance criteria.
218
+
219
+ - New here? Pick a [**good first issue**](https://github.com/himanshu231204/prompt-migrate/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
220
+ - Want to shape the design? Join an [**RFC discussion**](https://github.com/himanshu231204/prompt-migrate/issues?q=is%3Aissue+is%3Aopen+label%3Arfc).
221
+ - Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup and where code lives, and [`AGENTS.md`](AGENTS.md) for the project rules (they apply to people and AI coding agents alike).
222
+
223
+ ```bash
224
+ python -m pip install -e ".[dev]"
225
+ python -m pytest -q
226
+ ```
227
+
228
+ Design docs start at [`docs/HANDOFF.md`](docs/HANDOFF.md).
229
+
230
+ ## Community
231
+
232
+ - [Code of Conduct](CODE_OF_CONDUCT.md)
233
+ - Report security issues privately: see [`SECURITY.md`](SECURITY.md)
234
+ - Changes are listed in [`CHANGELOG.md`](CHANGELOG.md)
235
+
236
+ ## License
237
+
238
+ [MIT](LICENSE)
239
+
240
+ <!-- gumroad-footer -->
241
+ ---
242
+
243
+ ### More free resources
244
+
245
+ I share free visual notes, agent skills and guides on AI agents, Google ADK, RAG and LLMs.
246
+
247
+ [![Gumroad](https://img.shields.io/badge/Gumroad-free_notes_%26_skills-ff90e8?style=flat-square&logo=gumroad&logoColor=white)](https://himanshu231204.gumroad.com) → **[himanshu231204.gumroad.com](https://himanshu231204.gumroad.com)**
@@ -0,0 +1,223 @@
1
+ <p align="center">
2
+ <img src="assets/readme-banner.svg" alt="PromptMigrate — Alembic-style migrations for LLM prompts and AI agents" width="100%" />
3
+ </p>
4
+
5
+ <p align="center">
6
+ <a href="https://github.com/himanshu231204/prompt-migrate/actions/workflows/ci.yml"><img src="https://github.com/himanshu231204/prompt-migrate/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
7
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
8
+ <img src="https://img.shields.io/badge/python-3.10%2B-3776ab.svg?logo=python&logoColor=white" alt="Python 3.10+" />
9
+ <img src="https://img.shields.io/badge/runtime_deps-0_(stdlib_only)-2ea44f.svg" alt="Zero runtime dependencies" />
10
+ <a href="https://github.com/himanshu231204/prompt-migrate/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22"><img src="https://img.shields.io/github/issues/himanshu231204/prompt-migrate/good%20first%20issue?color=7057ff&label=good%20first%20issues" alt="Good first issues" /></a>
11
+ </p>
12
+
13
+ # PromptMigrate
14
+
15
+ **Alembic-style migrations for LLM prompts and AI agent configuration.** Keep prompts and agent configs as Git-tracked JSON, generate ordered, reviewable revisions, apply them to environments, roll them back, and fail CI when an environment drifts from history.
16
+
17
+ > [!NOTE]
18
+ > PromptMigrate is a **v0.1 local prototype**. Environments are local SQLite files, and nothing is deployed to Langfuse, OpenAI, Azure AI Foundry or any other runtime. See [what is and isn't guaranteed](#safety-and-integrity).
19
+
20
+ ## Why PromptMigrate?
21
+
22
+ Langfuse, MLflow, Agenta and promptctl already version and manage prompts. PromptMigrate focuses on something narrower: an **ordered migration protocol** for configuration, the way Alembic does it for database schemas.
23
+
24
+ - **Ordered history:** every revision names its predecessor, forming one linear chain.
25
+ - **Reversible:** each revision stores full before/after snapshots, so `downgrade` is deterministic.
26
+ - **Integrity-checked:** applied revisions are checksummed; editing one, or changing an environment by hand, is reported as drift.
27
+ - **CI-friendly:** stable exit codes and `--output json`.
28
+ - **Declarative and safe:** revisions are pure JSON, never executable code. The runtime uses only the Python standard library.
29
+
30
+ It's designed to sit alongside prompt registries, not replace them.
31
+
32
+ ## Install
33
+
34
+ Python 3.10 or newer. The PyPI distribution is named `promptmigrate-cli` (the name `promptmigrate` was already taken); the command and the import are both `promptmigrate`:
35
+
36
+ ```bash
37
+ python -m pip install promptmigrate-cli
38
+ promptmigrate --version
39
+ ```
40
+
41
+ To work on PromptMigrate itself, install from a clone instead:
42
+
43
+ ```bash
44
+ git clone https://github.com/himanshu231204/prompt-migrate.git
45
+ cd prompt-migrate
46
+ python -m pip install -e .
47
+ ```
48
+
49
+ ## Five-minute example
50
+
51
+ In a separate, empty project directory, run the example with the starter draft
52
+ that `init` creates. You can edit the draft before generating the first revision.
53
+
54
+ <!-- quickstart-smoke:start -->
55
+ ```bash
56
+ promptmigrate init
57
+ promptmigrate env list
58
+ promptmigrate env add qa
59
+ # Optional: edit .promptmigrate/drafts/assistant.json with the desired system prompt,
60
+ # model, temperature, tool specs, response schema, etc.
61
+ promptmigrate revision -m "initial assistant prompt"
62
+ promptmigrate history
63
+ promptmigrate plan --env dev --target head
64
+ promptmigrate upgrade head --env dev
65
+ promptmigrate check --env dev --require-head
66
+ promptmigrate get assistant --env dev
67
+ ```
68
+ <!-- quickstart-smoke:end -->
69
+
70
+ Then edit `.promptmigrate/drafts/assistant.json` and run:
71
+
72
+ ```bash
73
+ promptmigrate diff
74
+ promptmigrate revision -m "strengthen refusal instructions"
75
+ promptmigrate upgrade head --env staging
76
+ promptmigrate current --env staging
77
+ promptmigrate downgrade -1 --env staging
78
+ ```
79
+
80
+ A revision describes the change from the previous Git-tracked revision, **not from your local dev database**, so pull your team's latest revisions before generating one. For multi-agent systems, add more drafts such as `planner.json` or `reviewer.json`. Deleting a draft and generating a revision deletes that config in the target environment, reversibly.
81
+
82
+ A runnable two-agent walkthrough is in [`examples/multi-agent-basic/`](examples/multi-agent-basic/).
83
+
84
+ ## What a revision looks like
85
+
86
+ ```json
87
+ {
88
+ "format_version": 1,
89
+ "revision": "0123456789ab",
90
+ "down_revision": null,
91
+ "message": "initial assistant",
92
+ "created_at": "2026-10-29T00:00:00+00:00",
93
+ "changes": {
94
+ "assistant": {
95
+ "before": null,
96
+ "after": {
97
+ "messages": [{"role": "system", "content": "You are helpful."}],
98
+ "model": "provider/model-id",
99
+ "parameters": {"temperature": 0}
100
+ }
101
+ }
102
+ }
103
+ }
104
+ ```
105
+
106
+ `before` and `after` are full JSON snapshots, and `null` means the config is absent. One revision can change several configs in a single atomic transaction. Snapshots make reversal deterministic, at the cost of larger files and keeping old values in Git history.
107
+
108
+ ## How it works
109
+
110
+ ```mermaid
111
+ flowchart LR
112
+ D["drafts/*.json<br/>desired config"] -- "revision -m" --> V["versions/*.json<br/>ordered revisions (Git)"]
113
+ V -- "upgrade / downgrade" --> S[("states/#lt;env#gt;.sqlite3<br/>config + applied ledger")]
114
+ V -. "check: ledger and config<br/>must match history" .-> S
115
+ ```
116
+
117
+ `upgrade` and `downgrade` verify the environment against history, then change the configs and the applied-revision ledger together in one SQLite transaction. If anything doesn't match, the command fails without writing.
118
+
119
+ ## Commands
120
+
121
+ | Command | Behavior |
122
+ |---|---|
123
+ | `init` | Create the migration workspace and a starter draft |
124
+ | `diff` | Compare local drafts with the latest revision |
125
+ | `revision -m "..."` | Generate a revision from draft changes |
126
+ | `history` | Print the revision chain |
127
+ | `current --env dev` | Show an environment's current revision |
128
+ | `plan --env dev [--target head]` | Preview what an upgrade or downgrade would change; writes nothing |
129
+ | `upgrade head --env dev` | Apply pending revisions atomically |
130
+ | `downgrade -1 --env dev` | Undo the last applied revision (`base` reverts all) |
131
+ | `check --env dev --require-head` | Detect drift, edited applied revisions and pending revisions |
132
+ | `restamp --env dev` | Accept applied v0 revisions whose files changed only in line endings |
133
+ | `validate [--strict] [--drafts-clean]` | Check revision history, drafts and manifests without touching any environment |
134
+ | `get assistant --env dev` | Read a config from a local environment |
135
+ | `env add qa` / `env list` | Declare and list local environments |
136
+
137
+ Global flags: `--project <dir>` targets another project directory, and `--output json` prints machine-readable results. Exit codes are documented in [`docs/CLI_SPEC.md`](docs/CLI_SPEC.md).
138
+
139
+ ## Project layout
140
+
141
+ ```text
142
+ project/
143
+ .promptmigrate/
144
+ drafts/ # desired JSON configs (Git tracked)
145
+ versions/ # revisions with before/after snapshots (Git tracked)
146
+ environments.json # declared environments (Git tracked)
147
+ states/ # local SQLite state per environment (gitignored)
148
+ ```
149
+
150
+ > [!WARNING]
151
+ > `states/prod.sqlite3` is a **local file named prod**, not a production deployment. Production-like names print a warning for this reason.
152
+
153
+ ## Use in CI
154
+
155
+ In your project's workflow, install PromptMigrate from its repository, then replay every revision into a throwaway environment and verify it:
156
+
157
+ ```yaml
158
+ - run: python -m pip install "git+https://github.com/himanshu231204/prompt-migrate.git"
159
+ - run: promptmigrate validate --strict --drafts-clean
160
+ - run: promptmigrate upgrade head --env dev
161
+ - run: promptmigrate check --env dev --require-head
162
+ ```
163
+
164
+ `states/` is gitignored, so a fresh CI checkout starts every environment at the empty base. This job proves the revision history loads, applies cleanly in order from scratch, and verifies. It can't check a long-lived environment such as `staging`, because that state lives only on the machine that owns it; shared remote state is planned for Phase 3.
165
+
166
+ `validate` checks only the files in Git (history, drafts, manifests, secret allowlist) and exits 3 on any finding under `--strict`; `--drafts-clean` also fails when a draft edit has no revision yet. `check` exits non-zero on drift, an edited applied revision, or (with `--require-head`) pending revisions. It verifies **integrity, not prompt quality**: it doesn't measure answer quality or prompt-injection resistance.
167
+
168
+ ## Safety and integrity
169
+
170
+ **Guaranteed today:**
171
+
172
+ - Applying or reverting several revisions is atomic **inside one local SQLite database**.
173
+ - Applied revisions are checksummed. Editing one blocks that environment (v1 revisions ignore formatting-only changes).
174
+ - Out-of-band changes to an environment's configs are rejected as drift.
175
+ - History is one linear chain; parallel branches must be resolved first.
176
+ - Revisions are pure JSON; no migration code is ever executed.
177
+ - No provider API keys or network calls are needed.
178
+ - Secret-like values are refused in new revisions and redacted in `diff`/`get` output. Detection is heuristic, and secrets already in Git must be rotated.
179
+
180
+ **Not guaranteed yet:** transactions across model providers, locks across hosts, remote state, signed revisions, authentication, evaluation gates, canary releases or an append-only audit history. Don't use v0.1 to manage live production prompts or secrets.
181
+
182
+ ## Roadmap
183
+
184
+ The plan is in [`docs/ROADMAP.md`](docs/ROADMAP.md) and tracked as GitHub milestones:
185
+
186
+ 1. [**Phase 1: Harden the migration core**](https://github.com/himanshu231204/prompt-migrate/milestone/1) (in progress): concurrency and fault-injection tests, package smoke tests.
187
+ 2. [**Phase 2: Evaluation and policy gates**](https://github.com/himanshu231204/prompt-migrate/milestone/2)
188
+ 3. [**Phase 3: Production release protocol**](https://github.com/himanshu231204/prompt-migrate/milestone/3)
189
+ 4. [**Phase 4: Stable community release**](https://github.com/himanshu231204/prompt-migrate/milestone/4)
190
+
191
+ ## Contributing
192
+
193
+ Contributions are welcome. Every issue is a single task with acceptance criteria.
194
+
195
+ - New here? Pick a [**good first issue**](https://github.com/himanshu231204/prompt-migrate/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
196
+ - Want to shape the design? Join an [**RFC discussion**](https://github.com/himanshu231204/prompt-migrate/issues?q=is%3Aissue+is%3Aopen+label%3Arfc).
197
+ - Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup and where code lives, and [`AGENTS.md`](AGENTS.md) for the project rules (they apply to people and AI coding agents alike).
198
+
199
+ ```bash
200
+ python -m pip install -e ".[dev]"
201
+ python -m pytest -q
202
+ ```
203
+
204
+ Design docs start at [`docs/HANDOFF.md`](docs/HANDOFF.md).
205
+
206
+ ## Community
207
+
208
+ - [Code of Conduct](CODE_OF_CONDUCT.md)
209
+ - Report security issues privately: see [`SECURITY.md`](SECURITY.md)
210
+ - Changes are listed in [`CHANGELOG.md`](CHANGELOG.md)
211
+
212
+ ## License
213
+
214
+ [MIT](LICENSE)
215
+
216
+ <!-- gumroad-footer -->
217
+ ---
218
+
219
+ ### More free resources
220
+
221
+ I share free visual notes, agent skills and guides on AI agents, Google ADK, RAG and LLMs.
222
+
223
+ [![Gumroad](https://img.shields.io/badge/Gumroad-free_notes_%26_skills-ff90e8?style=flat-square&logo=gumroad&logoColor=white)](https://himanshu231204.gumroad.com) → **[himanshu231204.gumroad.com](https://himanshu231204.gumroad.com)**
@@ -0,0 +1,54 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "promptmigrate-cli"
7
+ version = "0.1.0"
8
+ description = "Alembic-inspired migration control for production AI prompts and agent configurations"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "Himanshu Kumar" }]
13
+ keywords = ["llm", "prompt", "migration", "version-control", "agents"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3.10",
18
+ "Programming Language :: Python :: 3.12",
19
+ "Programming Language :: Python :: 3.13",
20
+ "License :: OSI Approved :: MIT License",
21
+ "Topic :: Software Development :: Version Control",
22
+ ]
23
+
24
+ [project.scripts]
25
+ promptmigrate = "promptmigrate.cli:main"
26
+
27
+ [project.optional-dependencies]
28
+ dev = ["pytest>=8", "hypothesis>=6", "pytest-cov>=5", "mypy>=2.4,<2.5"]
29
+
30
+ [tool.setuptools.packages.find]
31
+ where = ["src"]
32
+
33
+ [tool.pytest.ini_options]
34
+ testpaths = ["tests"]
35
+ pythonpath = ["src"]
36
+
37
+ # Static type checking (issue #20). Start in lenient mode: check the annotated
38
+ # code under src/ without demanding full annotation coverage. Runtime stays
39
+ # stdlib-only; mypy is a dev-only tool. No python_version is pinned here, so the
40
+ # checker follows whatever interpreter CI / the developer runs (3.10-3.13).
41
+ # The dev extra caps mypy at one minor release: a new minor can add checks and turn
42
+ # main red with no code change, so raise the cap deliberately.
43
+ [tool.mypy]
44
+ files = ["src"]
45
+ # The goal of #20 is a working gate over the annotated code, not full annotation
46
+ # coverage. Missing imports are reported (nothing under src/ needs a stub today); the
47
+ # switches below stay lenient until the annotations reach that bar, and each one can be
48
+ # tightened on its own.
49
+ ignore_missing_imports = false
50
+ check_untyped_defs = false # bodies of unannotated functions are not checked yet
51
+ disallow_untyped_defs = false # annotated code only; demanding annotations everywhere is a later step
52
+ warn_return_any = false # returns of Any are expected until the protocols above are typed
53
+ warn_unused_ignores = true # a stale # type: ignore should surface, not linger
54
+ warn_unused_configs = false # keeps the config forward-compatible across mypy minors
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,21 @@
1
+ """PromptMigrate: declarative, reversible AI prompt configuration migrations."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ from .core import ( # noqa: E402 (the public facade, after the version so tooling can read it without imports)
6
+ ALLOWLIST_FILE, DriftError, InitializationError, IntegrityError, LegacyRevisionWarning, MigrationConflictError,
7
+ MigrationError, PendingRevisionsError, Revision, RevisionGraphError, SchemaError, SecretDetectedError,
8
+ SecretInHistoryWarning, SecretRedactedWarning, StaleAllowlistWarning, StorageError, TargetError, audit_secrets,
9
+ canonical, check, downgrade, draft_diff, env_add, env_list, get_config, init, load_allowlist, load_revisions,
10
+ pretty, read_drafts, redacted_config, redacted_diff, redacted_history, replay_revisions, require_init, revision,
11
+ root_dir, same, upgrade,
12
+ )
13
+
14
+ __all__ = [
15
+ "ALLOWLIST_FILE", "DriftError", "InitializationError", "IntegrityError", "LegacyRevisionWarning",
16
+ "MigrationConflictError", "MigrationError", "PendingRevisionsError", "Revision", "RevisionGraphError",
17
+ "SchemaError", "SecretDetectedError", "SecretInHistoryWarning", "SecretRedactedWarning", "StaleAllowlistWarning",
18
+ "StorageError", "TargetError", "audit_secrets", "canonical", "check", "downgrade", "draft_diff", "env_add",
19
+ "env_list", "get_config", "init", "load_allowlist", "load_revisions", "pretty", "read_drafts", "redacted_config",
20
+ "redacted_diff", "redacted_history", "replay_revisions", "require_init", "revision", "root_dir", "same", "upgrade",
21
+ ]
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())