@adamchanadam/agent-handoff-kit 0.3.3 → 0.3.4
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/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +70 -22
- package/docs/whatsnew/v0.3.4.md +17 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:`v0.3.
|
|
3
|
+
狀態:`v0.3.4` 已正式發佈到 GitHub 與 npm。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -434,6 +434,25 @@ function parseArgs(args) {
|
|
|
434
434
|
return { command, options };
|
|
435
435
|
}
|
|
436
436
|
|
|
437
|
+
// R-031.3 v0.3.4+: Helper to detect if PROJECT_INDEX template version metadata
|
|
438
|
+
// row is stale relative to current CLI version. Used by plan-time no-op detection
|
|
439
|
+
// guard to ensure metadata-only stale roots still trigger the upgrade ceremony
|
|
440
|
+
// (otherwise plan-time short-circuit returns before inject can run).
|
|
441
|
+
async function needsProjectIndexVersionInject(root, command, version) {
|
|
442
|
+
if (command !== "upgrade") return false;
|
|
443
|
+
try {
|
|
444
|
+
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
445
|
+
const text = await readFile(indexPath, "utf8");
|
|
446
|
+
const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
|
|
447
|
+
if (m && isStableSemver(m[1]) && compareSemver(m[1], version) < 0) {
|
|
448
|
+
return true;
|
|
449
|
+
}
|
|
450
|
+
} catch {
|
|
451
|
+
// ignore — silent if PROJECT_INDEX missing or unreadable
|
|
452
|
+
}
|
|
453
|
+
return false;
|
|
454
|
+
}
|
|
455
|
+
|
|
437
456
|
async function runInstall(command, root, options, version) {
|
|
438
457
|
const mode = await detectMode(root);
|
|
439
458
|
const plan = await buildPlan(root, command);
|
|
@@ -446,10 +465,17 @@ async function runInstall(command, root, options, version) {
|
|
|
446
465
|
const planMergeCount = plan.filter((item) => item.action === "merge").length;
|
|
447
466
|
const planConflictCount = plan.filter((item) => item.action === "conflict").length;
|
|
448
467
|
const planSkipCount = plan.filter((item) => item.action === "skip").length;
|
|
468
|
+
// R-031.3 v0.3.4+: metadata-only stale guard. If PROJECT_INDEX template version
|
|
469
|
+
// row is stale but structure is fully current (all v0.2.0+ files already present),
|
|
470
|
+
// plan create/merge/conflict are all 0 — but inject still needs to run. Without
|
|
471
|
+
// this guard, plan-time short-circuit returns before inject can fire, leaving
|
|
472
|
+
// root on stale version forever.
|
|
473
|
+
const projectIndexVersionNeedsInject = await needsProjectIndexVersionInject(root, command, version);
|
|
449
474
|
const isUpgradeNoopAtPlanTime = command === "upgrade"
|
|
450
475
|
&& planCreateCount === 0
|
|
451
476
|
&& planMergeCount === 0
|
|
452
|
-
&& planConflictCount === 0
|
|
477
|
+
&& planConflictCount === 0
|
|
478
|
+
&& !projectIndexVersionNeedsInject;
|
|
453
479
|
|
|
454
480
|
if (isUpgradeNoopAtPlanTime) {
|
|
455
481
|
printCard(version, "continuity ready", "o.o");
|
|
@@ -515,14 +541,24 @@ async function runInstall(command, root, options, version) {
|
|
|
515
541
|
created.push(item.targetRel);
|
|
516
542
|
}
|
|
517
543
|
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
544
|
+
for (const item of plan) {
|
|
545
|
+
if (item.action !== "merge") continue;
|
|
546
|
+
const backupPath = path.join(backupDir, item.targetRel);
|
|
547
|
+
await mkdir(path.dirname(backupPath), { recursive: true });
|
|
548
|
+
await copyFile(item.targetAbs, backupPath);
|
|
549
|
+
await writeFile(item.targetAbs, item.mergedText, "utf8");
|
|
550
|
+
merged.push(item.targetRel);
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
// R-031.3 v0.3.4+: Inject current CLI version into PROJECT_INDEX template version
|
|
554
|
+
// metadata row — placed AFTER the merge loop to avoid the ordering bug where merge
|
|
555
|
+
// overwrites inject. Merge writes item.mergedText computed at plan-build phase
|
|
556
|
+
// (which contains the pre-inject stale version row); if inject ran before merge,
|
|
557
|
+
// merge would silently revert it. R-016 still protected: only the metadata row
|
|
558
|
+
// mutates, user content rows (External Sources / Fact Base etc.) preserved.
|
|
559
|
+
// The captured metadataUpdated object is passed to writeMigrationReport so the
|
|
560
|
+
// audit trail records this mutation alongside file create/merge operations.
|
|
561
|
+
let metadataUpdated = null;
|
|
526
562
|
if (command === "upgrade" || created.includes("dev/PROJECT_INDEX.md")) {
|
|
527
563
|
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
528
564
|
try {
|
|
@@ -534,37 +570,39 @@ async function runInstall(command, root, options, version) {
|
|
|
534
570
|
`| Agent Handoff Kit template version | ${version} |`
|
|
535
571
|
);
|
|
536
572
|
await writeFile(indexPath, updated, "utf8");
|
|
573
|
+
metadataUpdated = {
|
|
574
|
+
file: "dev/PROJECT_INDEX.md",
|
|
575
|
+
field: "Agent Handoff Kit template version",
|
|
576
|
+
from: m[1],
|
|
577
|
+
to: version
|
|
578
|
+
};
|
|
537
579
|
}
|
|
538
580
|
} catch {
|
|
539
581
|
// ignore — doctor anchor (R-016) only checks row existence, not specific value.
|
|
540
582
|
}
|
|
541
583
|
}
|
|
542
584
|
|
|
543
|
-
for (const item of plan) {
|
|
544
|
-
if (item.action !== "merge") continue;
|
|
545
|
-
const backupPath = path.join(backupDir, item.targetRel);
|
|
546
|
-
await mkdir(path.dirname(backupPath), { recursive: true });
|
|
547
|
-
await copyFile(item.targetAbs, backupPath);
|
|
548
|
-
await writeFile(item.targetAbs, item.mergedText, "utf8");
|
|
549
|
-
merged.push(item.targetRel);
|
|
550
|
-
}
|
|
551
|
-
|
|
552
585
|
const skippedCount = plan.filter((item) => item.action === "skip").length;
|
|
553
586
|
|
|
554
587
|
// R-031 v0.3.1+: scenario branching. Upgrade no-op (零改動) short-circuits — skip
|
|
555
588
|
// migration report, self-check doctor, install banner, onboarding canonical phrase.
|
|
556
589
|
// Prevents misleading "安裝完成" framing when user is just verifying they are latest.
|
|
590
|
+
// R-031.3 v0.3.4+: also short-circuit only when metadata is current. If only the
|
|
591
|
+
// metadata row was stale (counts 0/0/0 but metadataUpdated truthy), user just
|
|
592
|
+
// received a substantive upgrade — proceed through full ceremony so doctor
|
|
593
|
+
// self-check confirms the inject result.
|
|
557
594
|
const isUpgradeNoop = command === "upgrade"
|
|
558
595
|
&& created.length === 0
|
|
559
596
|
&& merged.length === 0
|
|
560
|
-
&& conflicts.length === 0
|
|
597
|
+
&& conflicts.length === 0
|
|
598
|
+
&& !metadataUpdated;
|
|
561
599
|
|
|
562
600
|
if (isUpgradeNoop) {
|
|
563
601
|
printUpgradeNoopShortCircuit(version);
|
|
564
602
|
return;
|
|
565
603
|
}
|
|
566
604
|
|
|
567
|
-
const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
|
|
605
|
+
const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir, metadataUpdated);
|
|
568
606
|
printInstallSummary(version, command, mode, root, {
|
|
569
607
|
created: created.length,
|
|
570
608
|
merged: merged.length,
|
|
@@ -1460,7 +1498,7 @@ async function confirmWrite() {
|
|
|
1460
1498
|
}
|
|
1461
1499
|
}
|
|
1462
1500
|
|
|
1463
|
-
async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir) {
|
|
1501
|
+
async function writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir, metadataUpdated = null) {
|
|
1464
1502
|
const reportPath = path.join(migrationDir, "migration-report.md");
|
|
1465
1503
|
await mkdir(migrationDir, { recursive: true });
|
|
1466
1504
|
const skipped = plan.filter((item) => item.action === "skip").map((item) => item.targetRel);
|
|
@@ -1484,12 +1522,22 @@ async function writeMigrationReport(root, command, mode, plan, created, merged,
|
|
|
1484
1522
|
"## Conflicts",
|
|
1485
1523
|
...listOrNone(conflicts.map((item) => `${item.targetRel} - ${item.reason}`)),
|
|
1486
1524
|
"",
|
|
1525
|
+
// R-031.3 v0.3.4+: metadata updates are tracked separately from file create/merge
|
|
1526
|
+
// because they mutate specific rows inside an otherwise user-owned file rather
|
|
1527
|
+
// than replacing or merging the file as a whole. Audit trail completeness
|
|
1528
|
+
// requires this section even when create/merge/conflict counts are all 0.
|
|
1529
|
+
"## Metadata Updates",
|
|
1530
|
+
metadataUpdated
|
|
1531
|
+
? `- ${metadataUpdated.file}: ${metadataUpdated.field} ${metadataUpdated.from} → ${metadataUpdated.to}`
|
|
1532
|
+
: "- none",
|
|
1533
|
+
"",
|
|
1487
1534
|
"## Backup",
|
|
1488
1535
|
merged.length > 0 ? `- ${path.relative(root, backupDir)}` : "- none",
|
|
1489
1536
|
"",
|
|
1490
1537
|
"## Notes",
|
|
1491
1538
|
"- Existing files are preserved unless the installer can perform a bounded merge.",
|
|
1492
|
-
"- Files that cannot be safely merged are reported as conflicts and are not overwritten."
|
|
1539
|
+
"- Files that cannot be safely merged are reported as conflicts and are not overwritten.",
|
|
1540
|
+
"- Metadata Updates section tracks row-level mutations (R-031.3) distinct from file-level changes."
|
|
1493
1541
|
].join("\n");
|
|
1494
1542
|
await writeFile(reportPath, `${text}\n`, "utf8");
|
|
1495
1543
|
return reportPath;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# v0.3.4
|
|
2
|
+
|
|
3
|
+
## 本版新加咗咩
|
|
4
|
+
|
|
5
|
+
本版修補升級後版本敘事不一致的問題。既有專案執行 `upgrade` 後,`dev/PROJECT_INDEX.md` 內的「Agent Handoff Kit template version」資料列會在合併完成後再更新為目前 CLI 版本,避免先更新、後又被舊合併結果覆蓋。
|
|
6
|
+
|
|
7
|
+
升級工具也會辨認「只有版本資料列過期」的情況。即使沒有新增檔案、沒有合併檔案、沒有衝突,只要這一列仍是舊版本,就不會誤報「已經是最新版本,沒有檔案需要建立或合併」。
|
|
8
|
+
|
|
9
|
+
## 對你已有檔案嘅影響
|
|
10
|
+
|
|
11
|
+
本版只會更新 `dev/PROJECT_INDEX.md` 的 template version metadata。這一列屬工具維護的模板資料,不是你填寫的項目內容。你在 External Sources、Fact Base、Workspace Identity 等表格中填過的內容仍會保留。
|
|
12
|
+
|
|
13
|
+
升級紀錄也新增 metadata section,會寫明這次是否更新了版本資料列,方便日後追溯。
|
|
14
|
+
|
|
15
|
+
## 建議下一步
|
|
16
|
+
|
|
17
|
+
執行 `upgrade` 後再執行 `doctor`。若 `doctor` 顯示 `status: passed`,並且項目狀態速覽不再提示 root 落後 CLI,即代表這次熱修已生效。
|