@bbliong/aimp 0.2.0-beta.1 → 0.2.0-beta.2
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.
- package/CHANGELOG.md +6 -1
- package/README.md +152 -14
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## 0.2.0-beta.
|
|
3
|
+
## 0.2.0-beta.2 — unreleased
|
|
4
|
+
|
|
5
|
+
- Rewrote the English README with a command reference table and a complete Django workflow example.
|
|
6
|
+
- Added the safety tagline: “Never trust AI with your codebase. Let it touch only the mirror.”
|
|
7
|
+
|
|
8
|
+
## 0.2.0-beta.1 — 2026-09-13
|
|
4
9
|
|
|
5
10
|
- Rebuilt sync around Git porcelain NUL records and explicit path policy.
|
|
6
11
|
- Added recoverable transactions, immutable payloads, safe-copy checks, branch guards, and state migration.
|
package/README.md
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# aimp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Never trust AI with your codebase. Let it touch only the mirror.**
|
|
4
|
+
|
|
5
|
+
AIMP (AI Mirror Project) is a local CLI for working with AI in a separate mirror repository. The AI edits the mirror, the user reviews the report and changes, and AIMP applies the approved batch to the original project. AIMP does not call a model, run the application, create commits in the original project, or push to a remote.
|
|
4
6
|
|
|
5
7
|
## Install
|
|
6
8
|
|
|
@@ -10,19 +12,157 @@ cd /path/to/original-project
|
|
|
10
12
|
aimp
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
Node.js 22.14+
|
|
15
|
+
Node.js 22.14+ and Git 2.34+ are required. Linux and WSL2 on a Linux filesystem are supported in this beta. For terminals without the TUI, use `aimp --plain status --json`.
|
|
16
|
+
|
|
17
|
+
## Commands
|
|
18
|
+
|
|
19
|
+
Run `aimp` inside an original Git project to open the interactive terminal UI. The same commands can be run in plain mode with `aimp --plain <command>`.
|
|
20
|
+
|
|
21
|
+
| Command | Where | What it does |
|
|
22
|
+
| --- | --- | --- |
|
|
23
|
+
| `/init` | Original | Create or select the mirror for the current branch. |
|
|
24
|
+
| `/reinit` | Original | Replace or relocate the mirror after confirmation; retain the old contents in a backup. |
|
|
25
|
+
| `/use` | Original | Switch the mirror to the current original branch after checking for pending mirror work. |
|
|
26
|
+
| `/status` | Both | Show the original path, mirror path, branches, dirty state, pending AI changes, and tracked paths. |
|
|
27
|
+
| `/diff` | Both | List changed paths and show text diffs without writing files. |
|
|
28
|
+
| `/sync` | Original | Review AI changes, apply them to the original, and create a local `(synced)` checkpoint in the mirror. The original is never committed by AIMP. |
|
|
29
|
+
| `/sync-original-to-ai` | Original | Refresh the mirror from committed original changes. The original must be clean and the mirror must have no pending work. |
|
|
30
|
+
| `/serialize` | Mirror | Adopt selected mirror changes as the local mirror baseline without applying them to the original. |
|
|
31
|
+
| `/get-summary` | Both | Read the approved summary from `AIMP_REPORT.md`. |
|
|
32
|
+
| `/get-commit-message` | Both | Read the proposed commit subject from `AIMP_REPORT.md`. |
|
|
33
|
+
| `/recover` | Original | Resume an interrupted transaction. Use `/recover rollback` to restore its backup. |
|
|
34
|
+
| `/doctor` | Original | Check Git, repository shape, state, branch pairing, and recovery readiness. |
|
|
35
|
+
| `/migrate` | Original | Back up and migrate legacy AIMP state. Review it with `/adopt-baseline`. |
|
|
36
|
+
| `/adopt-baseline` | Original | Confirm a reviewed legacy baseline and enable synchronization. |
|
|
37
|
+
| `/adopt-policy` | Original | Review and accept a changed `.aimpignore` policy. |
|
|
38
|
+
| `/list` | Original | List registered branch pairs and mirror locations. |
|
|
39
|
+
| `/log` | Original | Show local transaction receipts. |
|
|
40
|
+
| `/language en\|id` | Both | Change the interface language. New projects default to English. |
|
|
41
|
+
| `/help` | Both | Show commands available in the current mode. |
|
|
42
|
+
| `/exit` | Both | Exit the UI and restore the previous terminal screen. |
|
|
43
|
+
|
|
44
|
+
Useful non-interactive forms are `aimp --version`, `aimp --help`, `aimp --plain status --json`, and `aimp --plain sync --dry-run`. Add `--profile` to the interactive command to print Git call and timing metrics.
|
|
45
|
+
|
|
46
|
+
## Example: review an AI change safely
|
|
47
|
+
|
|
48
|
+
This example uses a Django project at `~/projects/shop-api`, a feature branch named `feature/checkout-tax`, and a mirror at `~/ai-mirrors/shop-api-ai`.
|
|
49
|
+
|
|
50
|
+
### 1. Prepare the original project
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
cd ~/projects/shop-api
|
|
54
|
+
git switch -c feature/checkout-tax
|
|
55
|
+
cat > .aimpignore <<'EOF'
|
|
56
|
+
.env
|
|
57
|
+
*.local
|
|
58
|
+
config/production.yml
|
|
59
|
+
EOF
|
|
60
|
+
git status --short
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Keep real credentials in the original project. Put safe placeholders such as `.env.example` in the repository yourself; AIMP does not guess or sanitize credentials.
|
|
64
|
+
|
|
65
|
+
### 2. Create the mirror
|
|
66
|
+
|
|
67
|
+
```text
|
|
68
|
+
$ aimp
|
|
69
|
+
$ /init
|
|
70
|
+
Mirror folder [/home/alice/projects/shop-api-ai]: /home/alice/ai-mirrors/shop-api-ai
|
|
71
|
+
Mirror: /home/alice/ai-mirrors/shop-api-ai
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
AIMP creates an independent Git repository for `feature/checkout-tax`, copies only allowed files, and writes `AGENTS-AIMP.md` and `AIMP_REPORT.md`. The rules file tells the harness that this folder is the AI workspace and must not read the original project or credential stores.
|
|
75
|
+
|
|
76
|
+
### 3. Let any AI edit only the mirror
|
|
77
|
+
|
|
78
|
+
Open the mirror with the harness of your choice:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
cd ~/ai-mirrors/shop-api-ai
|
|
82
|
+
codex # or another harness/AI tool
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
For example, ask the AI to add tax calculation to `checkout/tax.py` and its tests. The AI edits the mirror only. Before leaving the mirror, it fills `AIMP_REPORT.md` and preserves the generated identity fields:
|
|
86
|
+
|
|
87
|
+
```markdown
|
|
88
|
+
Mirror-ID: 7d8f17e5-4f2b-4e6a-8c10-5a1c3d7f9b21
|
|
89
|
+
Branch: feature/checkout-tax
|
|
90
|
+
Batch-ID: 2c41a9b8-0d6e-4f70-9c33-7b2e1a8d5f44
|
|
91
|
+
Status: ready
|
|
92
|
+
|
|
93
|
+
## Summary
|
|
94
|
+
Added an 11% tax calculation for taxable checkout items and covered it with unit tests.
|
|
95
|
+
|
|
96
|
+
## Commit Message
|
|
97
|
+
Add checkout tax calculation
|
|
98
|
+
|
|
99
|
+
## Tests
|
|
100
|
+
pytest checkout/tests/test_tax.py
|
|
101
|
+
|
|
102
|
+
## Notes
|
|
103
|
+
Tax is applied only to taxable items; shipping remains exempt.
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The IDs above are examples. Keep the exact generated `Mirror-ID`, `Branch`, and `Batch-ID` values in your own report. `Status: ready` and all four sections are required before `/sync` can proceed.
|
|
107
|
+
|
|
108
|
+
### 4. Review and apply the batch
|
|
109
|
+
|
|
110
|
+
Return to the original project:
|
|
111
|
+
|
|
112
|
+
```text
|
|
113
|
+
$ cd ~/projects/shop-api
|
|
114
|
+
$ aimp
|
|
115
|
+
$ /status
|
|
116
|
+
Original: clean
|
|
117
|
+
Branch: feature/checkout-tax
|
|
118
|
+
AI copy: /home/alice/ai-mirrors/shop-api-ai
|
|
119
|
+
AI pending: true
|
|
120
|
+
|
|
121
|
+
$ /diff
|
|
122
|
+
modified "checkout/tax.py"
|
|
123
|
+
added "checkout/tests/test_tax.py"
|
|
124
|
+
|
|
125
|
+
$ /sync
|
|
126
|
+
Apply these files and create a local AI checkpoint? Original remains uncommitted. [y/N] y
|
|
127
|
+
Checkpoint AI: 4f2a...
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
AIMP copies the reviewed files to the original, leaves the original Git index and HEAD under your control, and creates one local mirror checkpoint whose message ends in `(synced)`. Review and test the original, then commit it with the project's normal workflow:
|
|
14
131
|
|
|
15
|
-
|
|
132
|
+
```bash
|
|
133
|
+
git diff
|
|
134
|
+
pytest checkout/tests/test_tax.py
|
|
135
|
+
git add checkout/tax.py checkout/tests/test_tax.py
|
|
136
|
+
git commit -m "Add checkout tax calculation"
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### 5. Refresh the mirror after an original commit
|
|
140
|
+
|
|
141
|
+
After you commit another change in the original, refresh the mirror manually:
|
|
142
|
+
|
|
143
|
+
```text
|
|
144
|
+
$ aimp
|
|
145
|
+
$ /sync-original-to-ai
|
|
146
|
+
Apply these files and create a local AI checkpoint? Original remains uncommitted. [y/N] y
|
|
147
|
+
```
|
|
16
148
|
|
|
17
|
-
|
|
18
|
-
2. Buka mirror dengan harness atau AI pilihan Anda. AIMP membuat `AGENTS-AIMP.md` dan `AIMP_REPORT.md`.
|
|
19
|
-
3. AI mengedit mirror dan mengisi laporan dengan `Status: ready`.
|
|
20
|
-
4. Dari original, jalankan `/status`, `/diff`, lalu `/sync`. Tinjau path, penghapusan, dan konfirmasi. File diterapkan ke original tanpa commit original; checkpoint lokal dibuat di mirror dengan pesan `(synced)`.
|
|
21
|
-
5. Commit perubahan original dengan workflow project Anda. Untuk memperbarui mirror dari commit original, gunakan `/sync-original-to-ai` setelah original bersih.
|
|
149
|
+
This command requires a clean original and no pending mirror work. If you switch to another original branch, run `/use` (or initialize it with `/init`) so the mirror branch remains paired explicitly.
|
|
22
150
|
|
|
23
|
-
|
|
151
|
+
### 6. Recover an interrupted operation
|
|
24
152
|
|
|
25
|
-
|
|
153
|
+
If the terminal or process stops during `/sync`, do not delete AIMP state or reset Git. Return to the original and run:
|
|
154
|
+
|
|
155
|
+
```text
|
|
156
|
+
$ aimp
|
|
157
|
+
$ /doctor
|
|
158
|
+
$ /recover
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Use `/recover rollback` when you want to restore the transaction backup instead of resuming it.
|
|
162
|
+
|
|
163
|
+
## Ignore policy and safety
|
|
164
|
+
|
|
165
|
+
`.aimpignore` lives at the original project root and defines exclusions in both directions, including for files already tracked by Git. Patterns follow Git's ignore syntax:
|
|
26
166
|
|
|
27
167
|
```gitignore
|
|
28
168
|
*.env
|
|
@@ -30,9 +170,7 @@ private/
|
|
|
30
170
|
!private/example.env
|
|
31
171
|
```
|
|
32
172
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
Jika transaksi terhenti, jalankan `/recover` untuk melanjutkan atau `/recover rollback` untuk memulihkan backup. Jangan menghapus folder state sebelum recovery selesai. Detail kontrak, batas platform, dan rencana rilis ada di `docs/`.
|
|
173
|
+
Excluded files are not copied, deleted, or applied. Use your own placeholders for AI configuration; AIMP does not automatically sanitize credentials. `AGENTS-AIMP.md` provides harness instructions, not an OS sandbox. An AI process running as the same user can still read other files allowed by the operating system. Detailed contracts, platform limits, and the release plan are in `docs/`.
|
|
36
174
|
|
|
37
175
|
## Development
|
|
38
176
|
|
|
@@ -42,4 +180,4 @@ npm run verify
|
|
|
42
180
|
npm pack --dry-run --json
|
|
43
181
|
```
|
|
44
182
|
|
|
45
|
-
|
|
183
|
+
Report bugs at <https://github.com/bbliong/aimp.dev/issues>. For security reports, see `SECURITY.md`.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bbliong/aimp",
|
|
3
|
-
"version": "0.2.0-beta.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.0-beta.2",
|
|
4
|
+
"description": "Never trust AI with your codebase. Let it touch only the mirror.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"aimp": "bin/aimp.js"
|