kiro-spec-engine 1.2.2 → 1.2.3
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 +17 -0
- package/docs/adoption-guide.md +506 -0
- package/docs/architecture.md +706 -0
- package/docs/developer-guide.md +615 -0
- package/docs/upgrade-guide.md +632 -0
- package/package.json +2 -1
|
@@ -0,0 +1,706 @@
|
|
|
1
|
+
# Architecture Documentation
|
|
2
|
+
|
|
3
|
+
This document provides detailed architecture diagrams and explanations for Kiro Spec Engine.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [System Architecture](#system-architecture)
|
|
8
|
+
- [Component Interactions](#component-interactions)
|
|
9
|
+
- [Data Flow](#data-flow)
|
|
10
|
+
- [Adoption Flow](#adoption-flow)
|
|
11
|
+
- [Upgrade Flow](#upgrade-flow)
|
|
12
|
+
- [Backup and Rollback Flow](#backup-and-rollback-flow)
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## System Architecture
|
|
17
|
+
|
|
18
|
+
### High-Level Architecture
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
22
|
+
│ User Interface │
|
|
23
|
+
│ (CLI Commands: kse adopt, │
|
|
24
|
+
│ kse upgrade, kse rollback) │
|
|
25
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
26
|
+
│
|
|
27
|
+
▼
|
|
28
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
29
|
+
│ Command Layer │
|
|
30
|
+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
31
|
+
│ │ adopt.js │ │ upgrade.js │ │ rollback.js │ │
|
|
32
|
+
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
33
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
34
|
+
│
|
|
35
|
+
▼
|
|
36
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
37
|
+
│ Core Systems Layer │
|
|
38
|
+
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
|
39
|
+
│ │ DetectionEngine │ │ MigrationEngine │ │ BackupSystem │ │
|
|
40
|
+
│ │ │ │ │ │ │ │
|
|
41
|
+
│ │ - analyze() │ │ - planUpgrade() │ │ - createBackup() │ │
|
|
42
|
+
│ │ - determineMode()│ │ - execute() │ │ - restore() │ │
|
|
43
|
+
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
|
|
44
|
+
│ │
|
|
45
|
+
│ ┌──────────────────┐ ┌──────────────────┐ │
|
|
46
|
+
│ │AdoptionStrategy │ │ VersionManager │ │
|
|
47
|
+
│ │ │ │ │ │
|
|
48
|
+
│ │ - Fresh │ │ - readVersion() │ │
|
|
49
|
+
│ │ - Partial │ │ - needsUpgrade() │ │
|
|
50
|
+
│ │ - Full │ │ - calcPath() │ │
|
|
51
|
+
│ └──────────────────┘ └──────────────────┘ │
|
|
52
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
53
|
+
│
|
|
54
|
+
▼
|
|
55
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
56
|
+
│ Utility Layer │
|
|
57
|
+
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
|
58
|
+
│ │ Validation │ │ File System │ │ Version Check │ │
|
|
59
|
+
│ │ Utils │ │ Utils │ │ │ │
|
|
60
|
+
│ │ │ │ │ │ │ │
|
|
61
|
+
│ │ - validateProj() │ │ - atomicWrite() │ │ - checkVersion() │ │
|
|
62
|
+
│ │ - validateVer() │ │ - safeCopy() │ │ - showWarning() │ │
|
|
63
|
+
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
|
|
64
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
65
|
+
│
|
|
66
|
+
▼
|
|
67
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
68
|
+
│ File System │
|
|
69
|
+
│ (.kiro/, backups/, etc.) │
|
|
70
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Component Interactions
|
|
76
|
+
|
|
77
|
+
### Adoption System Interaction
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
┌──────────┐
|
|
81
|
+
│ User │
|
|
82
|
+
└────┬─────┘
|
|
83
|
+
│ kse adopt
|
|
84
|
+
▼
|
|
85
|
+
┌─────────────────┐
|
|
86
|
+
│ adopt.js │
|
|
87
|
+
│ (Command) │
|
|
88
|
+
└────┬────────────┘
|
|
89
|
+
│
|
|
90
|
+
├─────────────────────────────────────────┐
|
|
91
|
+
│ │
|
|
92
|
+
▼ ▼
|
|
93
|
+
┌─────────────────┐ ┌─────────────────┐
|
|
94
|
+
│DetectionEngine │ │ BackupSystem │
|
|
95
|
+
│ │ │ │
|
|
96
|
+
│ 1. analyze() │ │ 1. createBackup()│
|
|
97
|
+
│ 2. detectType() │ │ (if needed) │
|
|
98
|
+
│ 3. detectConf() │ └─────────────────┘
|
|
99
|
+
└────┬────────────┘
|
|
100
|
+
│ analysis result
|
|
101
|
+
▼
|
|
102
|
+
┌─────────────────┐
|
|
103
|
+
│AdoptionStrategy │
|
|
104
|
+
│ │
|
|
105
|
+
│ 1. getStrategy()│
|
|
106
|
+
│ 2. execute() │
|
|
107
|
+
└────┬────────────┘
|
|
108
|
+
│
|
|
109
|
+
├──────────────┬──────────────┐
|
|
110
|
+
│ │ │
|
|
111
|
+
▼ ▼ ▼
|
|
112
|
+
┌─────────┐ ┌─────────┐ ┌─────────────┐
|
|
113
|
+
│ Fresh │ │ Partial │ │ Full │
|
|
114
|
+
│Adoption │ │Adoption │ │ Adoption │
|
|
115
|
+
└────┬────┘ └────┬────┘ └─────┬───────┘
|
|
116
|
+
│ │ │
|
|
117
|
+
└────────────┴──────────────┘
|
|
118
|
+
│
|
|
119
|
+
▼
|
|
120
|
+
┌───────────────┐
|
|
121
|
+
│VersionManager│
|
|
122
|
+
│ │
|
|
123
|
+
│ writeVersion()│
|
|
124
|
+
└───────────────┘
|
|
125
|
+
│
|
|
126
|
+
▼
|
|
127
|
+
┌───────────────┐
|
|
128
|
+
│ Validation │
|
|
129
|
+
│ │
|
|
130
|
+
│ validateProj()│
|
|
131
|
+
└───────────────┘
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Upgrade System Interaction
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
┌──────────┐
|
|
138
|
+
│ User │
|
|
139
|
+
└────┬─────┘
|
|
140
|
+
│ kse upgrade
|
|
141
|
+
▼
|
|
142
|
+
┌─────────────────┐
|
|
143
|
+
│ upgrade.js │
|
|
144
|
+
│ (Command) │
|
|
145
|
+
└────┬────────────┘
|
|
146
|
+
│
|
|
147
|
+
├─────────────────────────────────────────┐
|
|
148
|
+
│ │
|
|
149
|
+
▼ ▼
|
|
150
|
+
┌─────────────────┐ ┌─────────────────┐
|
|
151
|
+
│VersionManager │ │ BackupSystem │
|
|
152
|
+
│ │ │ │
|
|
153
|
+
│ 1. readVersion()│ │ 1. createBackup()│
|
|
154
|
+
│ 2. needsUpgrade()│ │ (mandatory) │
|
|
155
|
+
│ 3. calcPath() │ └─────────────────┘
|
|
156
|
+
└────┬────────────┘
|
|
157
|
+
│ upgrade path
|
|
158
|
+
▼
|
|
159
|
+
┌─────────────────┐
|
|
160
|
+
│MigrationEngine │
|
|
161
|
+
│ │
|
|
162
|
+
│ 1. planUpgrade()│
|
|
163
|
+
│ 2. loadMigr() │
|
|
164
|
+
│ 3. execute() │
|
|
165
|
+
└────┬────────────┘
|
|
166
|
+
│
|
|
167
|
+
│ for each version in path
|
|
168
|
+
▼
|
|
169
|
+
┌─────────────────┐
|
|
170
|
+
│Migration Script │
|
|
171
|
+
│ │
|
|
172
|
+
│ 1. migrate() │
|
|
173
|
+
│ 2. validate() │
|
|
174
|
+
└────┬────────────┘
|
|
175
|
+
│
|
|
176
|
+
▼
|
|
177
|
+
┌─────────────────┐
|
|
178
|
+
│VersionManager │
|
|
179
|
+
│ │
|
|
180
|
+
│ writeVersion() │
|
|
181
|
+
│ (update history)│
|
|
182
|
+
└────┬────────────┘
|
|
183
|
+
│
|
|
184
|
+
▼
|
|
185
|
+
┌─────────────────┐
|
|
186
|
+
│ Validation │
|
|
187
|
+
│ │
|
|
188
|
+
│ validateProj() │
|
|
189
|
+
└─────────────────┘
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## Data Flow
|
|
195
|
+
|
|
196
|
+
### Version Information Flow
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
200
|
+
│ version.json │
|
|
201
|
+
│ { │
|
|
202
|
+
│ "version": "1.2.0", │
|
|
203
|
+
│ "kseVersion": "1.2.0", │
|
|
204
|
+
│ "createdAt": "2026-01-23T00:00:00.000Z", │
|
|
205
|
+
│ "updatedAt": "2026-01-23T00:00:00.000Z", │
|
|
206
|
+
│ "upgradeHistory": [ │
|
|
207
|
+
│ { │
|
|
208
|
+
│ "from": "1.0.0", │
|
|
209
|
+
│ "to": "1.1.0", │
|
|
210
|
+
│ "timestamp": "2026-01-23T00:00:00.000Z", │
|
|
211
|
+
│ "kseVersion": "1.1.0" │
|
|
212
|
+
│ } │
|
|
213
|
+
│ ] │
|
|
214
|
+
│ } │
|
|
215
|
+
└─────────────────────────────────────────────────────────────┘
|
|
216
|
+
│
|
|
217
|
+
▼
|
|
218
|
+
┌───────────────────────┐
|
|
219
|
+
│ VersionManager │
|
|
220
|
+
│ │
|
|
221
|
+
│ - Parse version │
|
|
222
|
+
│ - Validate structure │
|
|
223
|
+
│ - Compare versions │
|
|
224
|
+
│ - Calculate path │
|
|
225
|
+
└───────────────────────┘
|
|
226
|
+
│
|
|
227
|
+
┌───────────────┼───────────────┐
|
|
228
|
+
│ │ │
|
|
229
|
+
▼ ▼ ▼
|
|
230
|
+
┌─────────┐ ┌─────────┐ ┌─────────┐
|
|
231
|
+
│ Adopt │ │Upgrade │ │Version │
|
|
232
|
+
│Command │ │Command │ │Checker │
|
|
233
|
+
└─────────┘ └─────────┘ └─────────┘
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Backup Data Flow
|
|
237
|
+
|
|
238
|
+
```
|
|
239
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
240
|
+
│ Project .kiro/ │
|
|
241
|
+
│ ├── specs/ │
|
|
242
|
+
│ ├── steering/ │
|
|
243
|
+
│ ├── tools/ │
|
|
244
|
+
│ └── version.json │
|
|
245
|
+
└─────────────────────────────────────────────────────────────┘
|
|
246
|
+
│
|
|
247
|
+
│ createBackup()
|
|
248
|
+
▼
|
|
249
|
+
┌───────────────────────┐
|
|
250
|
+
│ BackupSystem │
|
|
251
|
+
│ │
|
|
252
|
+
│ 1. Validate source │
|
|
253
|
+
│ 2. Create timestamp │
|
|
254
|
+
│ 3. Copy recursively │
|
|
255
|
+
│ 4. Validate backup │
|
|
256
|
+
└───────────────────────┘
|
|
257
|
+
│
|
|
258
|
+
▼
|
|
259
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
260
|
+
│ .kiro/backups/backup-{timestamp}/ │
|
|
261
|
+
│ ├── specs/ │
|
|
262
|
+
│ ├── steering/ │
|
|
263
|
+
│ ├── tools/ │
|
|
264
|
+
│ ├── version.json │
|
|
265
|
+
│ └── backup-info.json │
|
|
266
|
+
│ { │
|
|
267
|
+
│ "timestamp": "2026-01-23T12:00:00.000Z", │
|
|
268
|
+
│ "reason": "before-upgrade", │
|
|
269
|
+
│ "originalVersion": "1.0.0" │
|
|
270
|
+
│ } │
|
|
271
|
+
└─────────────────────────────────────────────────────────────┘
|
|
272
|
+
│
|
|
273
|
+
│ restore()
|
|
274
|
+
▼
|
|
275
|
+
┌───────────────────────┐
|
|
276
|
+
│ BackupSystem │
|
|
277
|
+
│ │
|
|
278
|
+
│ 1. Validate backup │
|
|
279
|
+
│ 2. Clear current │
|
|
280
|
+
│ 3. Copy back │
|
|
281
|
+
│ 4. Validate restore │
|
|
282
|
+
└───────────────────────┘
|
|
283
|
+
│
|
|
284
|
+
▼
|
|
285
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
286
|
+
│ Project .kiro/ │
|
|
287
|
+
│ (Restored to backup state) │
|
|
288
|
+
└─────────────────────────────────────────────────────────────┘
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## Adoption Flow
|
|
294
|
+
|
|
295
|
+
### Fresh Adoption Flow
|
|
296
|
+
|
|
297
|
+
```
|
|
298
|
+
START
|
|
299
|
+
│
|
|
300
|
+
▼
|
|
301
|
+
┌─────────────────────┐
|
|
302
|
+
│ Detect: No .kiro/ │
|
|
303
|
+
│ Mode: Fresh │
|
|
304
|
+
└──────┬──────────────┘
|
|
305
|
+
│
|
|
306
|
+
▼
|
|
307
|
+
┌─────────────────────┐
|
|
308
|
+
│ Create .kiro/ │
|
|
309
|
+
│ directory structure │
|
|
310
|
+
└──────┬──────────────┘
|
|
311
|
+
│
|
|
312
|
+
▼
|
|
313
|
+
┌─────────────────────┐
|
|
314
|
+
│ Copy template files:│
|
|
315
|
+
│ - specs/ │
|
|
316
|
+
│ - steering/ │
|
|
317
|
+
│ - tools/ │
|
|
318
|
+
│ - README.md │
|
|
319
|
+
└──────┬──────────────┘
|
|
320
|
+
│
|
|
321
|
+
▼
|
|
322
|
+
┌─────────────────────┐
|
|
323
|
+
│ Create version.json │
|
|
324
|
+
│ with current version│
|
|
325
|
+
└──────┬──────────────┘
|
|
326
|
+
│
|
|
327
|
+
▼
|
|
328
|
+
┌─────────────────────┐
|
|
329
|
+
│ Validate structure │
|
|
330
|
+
└──────┬──────────────┘
|
|
331
|
+
│
|
|
332
|
+
▼
|
|
333
|
+
END
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### Partial Adoption Flow
|
|
337
|
+
|
|
338
|
+
```
|
|
339
|
+
START
|
|
340
|
+
│
|
|
341
|
+
▼
|
|
342
|
+
┌─────────────────────┐
|
|
343
|
+
│ Detect: Partial │
|
|
344
|
+
│ .kiro/ exists but │
|
|
345
|
+
│ incomplete │
|
|
346
|
+
└──────┬──────────────┘
|
|
347
|
+
│
|
|
348
|
+
▼
|
|
349
|
+
┌─────────────────────┐
|
|
350
|
+
│ Create backup │
|
|
351
|
+
│ (optional) │
|
|
352
|
+
└──────┬──────────────┘
|
|
353
|
+
│
|
|
354
|
+
▼
|
|
355
|
+
┌─────────────────────┐
|
|
356
|
+
│ Analyze missing │
|
|
357
|
+
│ components │
|
|
358
|
+
└──────┬──────────────┘
|
|
359
|
+
│
|
|
360
|
+
▼
|
|
361
|
+
┌─────────────────────┐
|
|
362
|
+
│ Add missing: │
|
|
363
|
+
│ - directories │
|
|
364
|
+
│ - template files │
|
|
365
|
+
│ - version.json │
|
|
366
|
+
└──────┬──────────────┘
|
|
367
|
+
│
|
|
368
|
+
▼
|
|
369
|
+
┌─────────────────────┐
|
|
370
|
+
│ Preserve existing: │
|
|
371
|
+
│ - specs/ │
|
|
372
|
+
│ - user content │
|
|
373
|
+
└──────┬──────────────┘
|
|
374
|
+
│
|
|
375
|
+
▼
|
|
376
|
+
┌─────────────────────┐
|
|
377
|
+
│ Validate structure │
|
|
378
|
+
└──────┬──────────────┘
|
|
379
|
+
│
|
|
380
|
+
▼
|
|
381
|
+
END
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
### Full Adoption Flow
|
|
385
|
+
|
|
386
|
+
```
|
|
387
|
+
START
|
|
388
|
+
│
|
|
389
|
+
▼
|
|
390
|
+
┌─────────────────────┐
|
|
391
|
+
│ Detect: Full │
|
|
392
|
+
│ .kiro/ complete but │
|
|
393
|
+
│ old version │
|
|
394
|
+
└──────┬──────────────┘
|
|
395
|
+
│
|
|
396
|
+
▼
|
|
397
|
+
┌─────────────────────┐
|
|
398
|
+
│ Create backup │
|
|
399
|
+
│ (mandatory) │
|
|
400
|
+
└──────┬──────────────┘
|
|
401
|
+
│
|
|
402
|
+
▼
|
|
403
|
+
┌─────────────────────┐
|
|
404
|
+
│ Calculate upgrade │
|
|
405
|
+
│ path │
|
|
406
|
+
└──────┬──────────────┘
|
|
407
|
+
│
|
|
408
|
+
▼
|
|
409
|
+
┌─────────────────────┐
|
|
410
|
+
│ Execute migrations │
|
|
411
|
+
│ (if needed) │
|
|
412
|
+
└──────┬──────────────┘
|
|
413
|
+
│
|
|
414
|
+
▼
|
|
415
|
+
┌─────────────────────┐
|
|
416
|
+
│ Update template │
|
|
417
|
+
│ files (non-user) │
|
|
418
|
+
└──────┬──────────────┘
|
|
419
|
+
│
|
|
420
|
+
▼
|
|
421
|
+
┌─────────────────────┐
|
|
422
|
+
│ Update version.json │
|
|
423
|
+
│ with history │
|
|
424
|
+
└──────┬──────────────┘
|
|
425
|
+
│
|
|
426
|
+
▼
|
|
427
|
+
┌─────────────────────┐
|
|
428
|
+
│ Validate structure │
|
|
429
|
+
└──────┬──────────────┘
|
|
430
|
+
│
|
|
431
|
+
▼
|
|
432
|
+
END
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
---
|
|
436
|
+
|
|
437
|
+
## Upgrade Flow
|
|
438
|
+
|
|
439
|
+
### Standard Upgrade Flow
|
|
440
|
+
|
|
441
|
+
```
|
|
442
|
+
START
|
|
443
|
+
│
|
|
444
|
+
▼
|
|
445
|
+
┌─────────────────────┐
|
|
446
|
+
│ Read current version│
|
|
447
|
+
│ from version.json │
|
|
448
|
+
└──────┬──────────────┘
|
|
449
|
+
│
|
|
450
|
+
▼
|
|
451
|
+
┌─────────────────────┐
|
|
452
|
+
│ Check if upgrade │
|
|
453
|
+
│ needed │
|
|
454
|
+
└──────┬──────────────┘
|
|
455
|
+
│ Yes
|
|
456
|
+
▼
|
|
457
|
+
┌─────────────────────┐
|
|
458
|
+
│ Create backup │
|
|
459
|
+
│ (mandatory) │
|
|
460
|
+
└──────┬──────────────┘
|
|
461
|
+
│
|
|
462
|
+
▼
|
|
463
|
+
┌─────────────────────┐
|
|
464
|
+
│ Calculate upgrade │
|
|
465
|
+
│ path with │
|
|
466
|
+
│ intermediate │
|
|
467
|
+
│ versions │
|
|
468
|
+
└──────┬──────────────┘
|
|
469
|
+
│
|
|
470
|
+
▼
|
|
471
|
+
┌─────────────────────┐
|
|
472
|
+
│ For each version │
|
|
473
|
+
│ in path: │
|
|
474
|
+
│ │
|
|
475
|
+
│ ┌─────────────────┐ │
|
|
476
|
+
│ │ Load migration │ │
|
|
477
|
+
│ │ script │ │
|
|
478
|
+
│ └────────┬────────┘ │
|
|
479
|
+
│ │ │
|
|
480
|
+
│ ▼ │
|
|
481
|
+
│ ┌─────────────────┐ │
|
|
482
|
+
│ │ Execute │ │
|
|
483
|
+
│ │ migrate() │ │
|
|
484
|
+
│ └────────┬────────┘ │
|
|
485
|
+
│ │ │
|
|
486
|
+
│ ▼ │
|
|
487
|
+
│ ┌─────────────────┐ │
|
|
488
|
+
│ │ Validate │ │
|
|
489
|
+
│ │ result │ │
|
|
490
|
+
│ └────────┬────────┘ │
|
|
491
|
+
│ │ │
|
|
492
|
+
│ ▼ │
|
|
493
|
+
│ ┌─────────────────┐ │
|
|
494
|
+
│ │ Update version │ │
|
|
495
|
+
│ │ and history │ │
|
|
496
|
+
│ └─────────────────┘ │
|
|
497
|
+
└──────┬──────────────┘
|
|
498
|
+
│
|
|
499
|
+
▼
|
|
500
|
+
┌─────────────────────┐
|
|
501
|
+
│ Final validation │
|
|
502
|
+
└──────┬──────────────┘
|
|
503
|
+
│
|
|
504
|
+
▼
|
|
505
|
+
END
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
### Upgrade with Rollback Flow
|
|
509
|
+
|
|
510
|
+
```
|
|
511
|
+
START
|
|
512
|
+
│
|
|
513
|
+
▼
|
|
514
|
+
┌─────────────────────┐
|
|
515
|
+
│ Begin upgrade │
|
|
516
|
+
└──────┬──────────────┘
|
|
517
|
+
│
|
|
518
|
+
▼
|
|
519
|
+
┌─────────────────────┐
|
|
520
|
+
│ Create backup │
|
|
521
|
+
│ backup-id: ABC123 │
|
|
522
|
+
└──────┬──────────────┘
|
|
523
|
+
│
|
|
524
|
+
▼
|
|
525
|
+
┌─────────────────────┐
|
|
526
|
+
│ Execute migration │
|
|
527
|
+
└──────┬──────────────┘
|
|
528
|
+
│
|
|
529
|
+
│ ERROR!
|
|
530
|
+
▼
|
|
531
|
+
┌─────────────────────┐
|
|
532
|
+
│ Catch error │
|
|
533
|
+
│ Log details │
|
|
534
|
+
└──────┬──────────────┘
|
|
535
|
+
│
|
|
536
|
+
▼
|
|
537
|
+
┌─────────────────────┐
|
|
538
|
+
│ Restore from backup │
|
|
539
|
+
│ backup-id: ABC123 │
|
|
540
|
+
└──────┬──────────────┘
|
|
541
|
+
│
|
|
542
|
+
▼
|
|
543
|
+
┌─────────────────────┐
|
|
544
|
+
│ Validate restore │
|
|
545
|
+
└──────┬──────────────┘
|
|
546
|
+
│
|
|
547
|
+
▼
|
|
548
|
+
┌─────────────────────┐
|
|
549
|
+
│ Report error to user│
|
|
550
|
+
│ with recovery steps │
|
|
551
|
+
└──────┬──────────────┘
|
|
552
|
+
│
|
|
553
|
+
▼
|
|
554
|
+
END
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
---
|
|
558
|
+
|
|
559
|
+
## Backup and Rollback Flow
|
|
560
|
+
|
|
561
|
+
### Backup Creation Flow
|
|
562
|
+
|
|
563
|
+
```
|
|
564
|
+
START
|
|
565
|
+
│
|
|
566
|
+
▼
|
|
567
|
+
┌─────────────────────┐
|
|
568
|
+
│ Validate source │
|
|
569
|
+
│ .kiro/ exists │
|
|
570
|
+
└──────┬──────────────┘
|
|
571
|
+
│
|
|
572
|
+
▼
|
|
573
|
+
┌─────────────────────┐
|
|
574
|
+
│ Generate backup ID │
|
|
575
|
+
│ backup-{timestamp} │
|
|
576
|
+
└──────┬──────────────┘
|
|
577
|
+
│
|
|
578
|
+
▼
|
|
579
|
+
┌─────────────────────┐
|
|
580
|
+
│ Create backup dir │
|
|
581
|
+
│ .kiro/backups/... │
|
|
582
|
+
└──────┬──────────────┘
|
|
583
|
+
│
|
|
584
|
+
▼
|
|
585
|
+
┌─────────────────────┐
|
|
586
|
+
│ Copy .kiro/ content │
|
|
587
|
+
│ recursively │
|
|
588
|
+
└──────┬──────────────┘
|
|
589
|
+
│
|
|
590
|
+
▼
|
|
591
|
+
┌─────────────────────┐
|
|
592
|
+
│ Create backup-info │
|
|
593
|
+
│ .json with metadata │
|
|
594
|
+
└──────┬──────────────┘
|
|
595
|
+
│
|
|
596
|
+
▼
|
|
597
|
+
┌─────────────────────┐
|
|
598
|
+
│ Validate backup │
|
|
599
|
+
│ integrity │
|
|
600
|
+
└──────┬──────────────┘
|
|
601
|
+
│
|
|
602
|
+
▼
|
|
603
|
+
┌─────────────────────┐
|
|
604
|
+
│ Return backup ID │
|
|
605
|
+
└──────┬──────────────┘
|
|
606
|
+
│
|
|
607
|
+
▼
|
|
608
|
+
END
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
### Rollback Flow
|
|
612
|
+
|
|
613
|
+
```
|
|
614
|
+
START
|
|
615
|
+
│
|
|
616
|
+
▼
|
|
617
|
+
┌─────────────────────┐
|
|
618
|
+
│ List available │
|
|
619
|
+
│ backups │
|
|
620
|
+
└──────┬──────────────┘
|
|
621
|
+
│
|
|
622
|
+
▼
|
|
623
|
+
┌─────────────────────┐
|
|
624
|
+
│ User selects backup │
|
|
625
|
+
│ or auto-select │
|
|
626
|
+
│ latest │
|
|
627
|
+
└──────┬──────────────┘
|
|
628
|
+
│
|
|
629
|
+
▼
|
|
630
|
+
┌─────────────────────┐
|
|
631
|
+
│ Validate backup │
|
|
632
|
+
│ integrity │
|
|
633
|
+
└──────┬──────────────┘
|
|
634
|
+
│
|
|
635
|
+
▼
|
|
636
|
+
┌─────────────────────┐
|
|
637
|
+
│ Create safety backup│
|
|
638
|
+
│ of current state │
|
|
639
|
+
└──────┬──────────────┘
|
|
640
|
+
│
|
|
641
|
+
▼
|
|
642
|
+
┌─────────────────────┐
|
|
643
|
+
│ Clear current │
|
|
644
|
+
│ .kiro/ content │
|
|
645
|
+
└──────┬──────────────┘
|
|
646
|
+
│
|
|
647
|
+
▼
|
|
648
|
+
┌─────────────────────┐
|
|
649
|
+
│ Copy backup content │
|
|
650
|
+
│ to .kiro/ │
|
|
651
|
+
└──────┬──────────────┘
|
|
652
|
+
│
|
|
653
|
+
▼
|
|
654
|
+
┌─────────────────────┐
|
|
655
|
+
│ Validate restore │
|
|
656
|
+
└──────┬──────────────┘
|
|
657
|
+
│
|
|
658
|
+
▼
|
|
659
|
+
┌─────────────────────┐
|
|
660
|
+
│ Report success │
|
|
661
|
+
└──────┬──────────────┘
|
|
662
|
+
│
|
|
663
|
+
▼
|
|
664
|
+
END
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
---
|
|
668
|
+
|
|
669
|
+
## Error Handling Architecture
|
|
670
|
+
|
|
671
|
+
### Error Categories and Handling
|
|
672
|
+
|
|
673
|
+
```
|
|
674
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
675
|
+
│ Error Categories │
|
|
676
|
+
├─────────────────────────────────────────────────────────────┤
|
|
677
|
+
│ │
|
|
678
|
+
│ 1. Pre-Operation Errors │
|
|
679
|
+
│ - Invalid project path │
|
|
680
|
+
│ - Missing dependencies │
|
|
681
|
+
│ - Permission errors │
|
|
682
|
+
│ → Action: Abort before any changes │
|
|
683
|
+
│ │
|
|
684
|
+
│ 2. Operation Errors │
|
|
685
|
+
│ - File system errors │
|
|
686
|
+
│ - Migration script errors │
|
|
687
|
+
│ - Validation failures │
|
|
688
|
+
│ → Action: Rollback to backup │
|
|
689
|
+
│ │
|
|
690
|
+
│ 3. Backup Errors │
|
|
691
|
+
│ - Backup creation failed │
|
|
692
|
+
│ - Backup validation failed │
|
|
693
|
+
│ → Action: Abort operation │
|
|
694
|
+
│ │
|
|
695
|
+
│ 4. Rollback Errors │
|
|
696
|
+
│ - Restore failed │
|
|
697
|
+
│ - Backup corrupted │
|
|
698
|
+
│ → Action: Manual recovery required │
|
|
699
|
+
│ │
|
|
700
|
+
└─────────────────────────────────────────────────────────────┘
|
|
701
|
+
```
|
|
702
|
+
|
|
703
|
+
---
|
|
704
|
+
|
|
705
|
+
**Version**: 1.0
|
|
706
|
+
**Last Updated**: 2026-01-23
|