@adamchanadam/agent-handoff-kit 0.3.2 → 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 +131 -42
- package/docs/whatsnew/v0.3.3.md +13 -0
- 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");
|
|
@@ -467,6 +493,23 @@ async function runInstall(command, root, options, version) {
|
|
|
467
493
|
return;
|
|
468
494
|
}
|
|
469
495
|
|
|
496
|
+
// R-031.3 v0.3.3+: For upgrade scenarios, capture pre-upgrade root template version
|
|
497
|
+
// before the create/merge/inject loops mutate PROJECT_INDEX. This snapshot is later
|
|
498
|
+
// passed to printWhatsnew so the version range narrative reflects the actual user
|
|
499
|
+
// journey (v{pre-upgrade} → v{current CLI}), not the post-inject state which would
|
|
500
|
+
// make printWhatsnew see fromVersion == toVersion and skip the summary entirely.
|
|
501
|
+
let preUpgradeRootVersion = null;
|
|
502
|
+
if (command === "upgrade") {
|
|
503
|
+
try {
|
|
504
|
+
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
505
|
+
const text = await readFile(indexPath, "utf8");
|
|
506
|
+
const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
|
|
507
|
+
if (m) preUpgradeRootVersion = m[1];
|
|
508
|
+
} catch {
|
|
509
|
+
// ignore
|
|
510
|
+
}
|
|
511
|
+
}
|
|
512
|
+
|
|
470
513
|
printPlan(command, root, mode, plan, version);
|
|
471
514
|
|
|
472
515
|
if (options.dryRun) {
|
|
@@ -498,12 +541,25 @@ async function runInstall(command, root, options, version) {
|
|
|
498
541
|
created.push(item.targetRel);
|
|
499
542
|
}
|
|
500
543
|
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
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;
|
|
562
|
+
if (command === "upgrade" || created.includes("dev/PROJECT_INDEX.md")) {
|
|
507
563
|
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
508
564
|
try {
|
|
509
565
|
const text = await readFile(indexPath, "utf8");
|
|
@@ -514,38 +570,39 @@ async function runInstall(command, root, options, version) {
|
|
|
514
570
|
`| Agent Handoff Kit template version | ${version} |`
|
|
515
571
|
);
|
|
516
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
|
+
};
|
|
517
579
|
}
|
|
518
580
|
} catch {
|
|
519
|
-
// ignore —
|
|
520
|
-
// checks for the row's existence, not a specific version.
|
|
581
|
+
// ignore — doctor anchor (R-016) only checks row existence, not specific value.
|
|
521
582
|
}
|
|
522
583
|
}
|
|
523
584
|
|
|
524
|
-
for (const item of plan) {
|
|
525
|
-
if (item.action !== "merge") continue;
|
|
526
|
-
const backupPath = path.join(backupDir, item.targetRel);
|
|
527
|
-
await mkdir(path.dirname(backupPath), { recursive: true });
|
|
528
|
-
await copyFile(item.targetAbs, backupPath);
|
|
529
|
-
await writeFile(item.targetAbs, item.mergedText, "utf8");
|
|
530
|
-
merged.push(item.targetRel);
|
|
531
|
-
}
|
|
532
|
-
|
|
533
585
|
const skippedCount = plan.filter((item) => item.action === "skip").length;
|
|
534
586
|
|
|
535
587
|
// R-031 v0.3.1+: scenario branching. Upgrade no-op (零改動) short-circuits — skip
|
|
536
588
|
// migration report, self-check doctor, install banner, onboarding canonical phrase.
|
|
537
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.
|
|
538
594
|
const isUpgradeNoop = command === "upgrade"
|
|
539
595
|
&& created.length === 0
|
|
540
596
|
&& merged.length === 0
|
|
541
|
-
&& conflicts.length === 0
|
|
597
|
+
&& conflicts.length === 0
|
|
598
|
+
&& !metadataUpdated;
|
|
542
599
|
|
|
543
600
|
if (isUpgradeNoop) {
|
|
544
601
|
printUpgradeNoopShortCircuit(version);
|
|
545
602
|
return;
|
|
546
603
|
}
|
|
547
604
|
|
|
548
|
-
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);
|
|
549
606
|
printInstallSummary(version, command, mode, root, {
|
|
550
607
|
created: created.length,
|
|
551
608
|
merged: merged.length,
|
|
@@ -555,12 +612,12 @@ async function runInstall(command, root, options, version) {
|
|
|
555
612
|
reportRel: path.relative(root, report)
|
|
556
613
|
});
|
|
557
614
|
|
|
558
|
-
// R-031 v0.3.1+: install vs upgrade narrative split.
|
|
559
|
-
//
|
|
560
|
-
//
|
|
561
|
-
//
|
|
615
|
+
// R-031 v0.3.1+: install vs upgrade narrative split.
|
|
616
|
+
// R-031.2 v0.3.2+: printUpgradeNextSteps async (awaits inline whatsnew print).
|
|
617
|
+
// R-031.3 v0.3.3+: pass preUpgradeRootVersion so whatsnew narrative reflects the
|
|
618
|
+
// actual user journey (v{pre-upgrade} → v{current}), not the post-inject state.
|
|
562
619
|
if (command === "upgrade") {
|
|
563
|
-
await printUpgradeNextSteps(root, conflicts.length, version);
|
|
620
|
+
await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
|
|
564
621
|
} else {
|
|
565
622
|
printInstallNextSteps(root, conflicts.length);
|
|
566
623
|
}
|
|
@@ -1441,7 +1498,7 @@ async function confirmWrite() {
|
|
|
1441
1498
|
}
|
|
1442
1499
|
}
|
|
1443
1500
|
|
|
1444
|
-
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) {
|
|
1445
1502
|
const reportPath = path.join(migrationDir, "migration-report.md");
|
|
1446
1503
|
await mkdir(migrationDir, { recursive: true });
|
|
1447
1504
|
const skipped = plan.filter((item) => item.action === "skip").map((item) => item.targetRel);
|
|
@@ -1465,12 +1522,22 @@ async function writeMigrationReport(root, command, mode, plan, created, merged,
|
|
|
1465
1522
|
"## Conflicts",
|
|
1466
1523
|
...listOrNone(conflicts.map((item) => `${item.targetRel} - ${item.reason}`)),
|
|
1467
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
|
+
"",
|
|
1468
1534
|
"## Backup",
|
|
1469
1535
|
merged.length > 0 ? `- ${path.relative(root, backupDir)}` : "- none",
|
|
1470
1536
|
"",
|
|
1471
1537
|
"## Notes",
|
|
1472
1538
|
"- Existing files are preserved unless the installer can perform a bounded merge.",
|
|
1473
|
-
"- 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."
|
|
1474
1541
|
].join("\n");
|
|
1475
1542
|
await writeFile(reportPath, `${text}\n`, "utf8");
|
|
1476
1543
|
return reportPath;
|
|
@@ -1623,7 +1690,7 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1623
1690
|
// R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
|
|
1624
1691
|
// (`printInstallNextSteps`) because the user is not first-time; pushing them through
|
|
1625
1692
|
// the onboarding canonical phrase resets context they already have.
|
|
1626
|
-
async function printUpgradeNextSteps(root, conflictCount, version) {
|
|
1693
|
+
async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
|
|
1627
1694
|
console.log("");
|
|
1628
1695
|
console.log("============================================================");
|
|
1629
1696
|
console.log("✅ 升級完成:管治架構檔案已更新到最新版本");
|
|
@@ -1635,10 +1702,11 @@ async function printUpgradeNextSteps(root, conflictCount, version) {
|
|
|
1635
1702
|
console.log("");
|
|
1636
1703
|
}
|
|
1637
1704
|
// R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
|
|
1638
|
-
// version (and any intermediate versions the user skipped)
|
|
1639
|
-
//
|
|
1640
|
-
//
|
|
1641
|
-
|
|
1705
|
+
// version (and any intermediate versions the user skipped).
|
|
1706
|
+
// R-031.3 v0.3.3+: fromVersion now uses pre-upgrade snapshot (captured before
|
|
1707
|
+
// inject mutated PROJECT_INDEX), so the range narrative reflects actual user
|
|
1708
|
+
// journey instead of degenerate v{current} → v{current}.
|
|
1709
|
+
await printWhatsnew(root, version, preUpgradeRootVersion);
|
|
1642
1710
|
console.log("📋 如你正在進行中的工作 session 已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
|
|
1643
1711
|
console.log("");
|
|
1644
1712
|
console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
|
|
@@ -1655,15 +1723,20 @@ async function printUpgradeNextSteps(root, conflictCount, version) {
|
|
|
1655
1723
|
// upgrade; R-016 preserves this row so it still reflects the prior state after
|
|
1656
1724
|
// upgrade finishes). toVersion = current CLI version. Range is exclusive-fromVersion
|
|
1657
1725
|
// inclusive-toVersion. Limit to first + last when crossing > 3 versions (elide middle).
|
|
1658
|
-
async function printWhatsnew(root, toVersion) {
|
|
1659
|
-
|
|
1660
|
-
|
|
1661
|
-
|
|
1662
|
-
|
|
1663
|
-
|
|
1664
|
-
|
|
1665
|
-
|
|
1666
|
-
|
|
1726
|
+
async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
1727
|
+
// R-031.3 v0.3.3+: fromVersion sourced from explicit override (pre-upgrade snapshot)
|
|
1728
|
+
// when called from upgrade flow; falls back to reading current PROJECT_INDEX
|
|
1729
|
+
// template version row otherwise.
|
|
1730
|
+
let fromVersion = fromVersionOverride ?? null;
|
|
1731
|
+
if (!fromVersion) {
|
|
1732
|
+
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
1733
|
+
try {
|
|
1734
|
+
const text = await readFile(indexPath, "utf8");
|
|
1735
|
+
const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
|
|
1736
|
+
if (m) fromVersion = m[1];
|
|
1737
|
+
} catch {
|
|
1738
|
+
return;
|
|
1739
|
+
}
|
|
1667
1740
|
}
|
|
1668
1741
|
if (!fromVersion || !isStableSemver(fromVersion) || compareSemver(fromVersion, toVersion) >= 0) {
|
|
1669
1742
|
return;
|
|
@@ -1692,7 +1765,23 @@ async function printWhatsnew(root, toVersion) {
|
|
|
1692
1765
|
return;
|
|
1693
1766
|
}
|
|
1694
1767
|
|
|
1695
|
-
|
|
1768
|
+
// R-031.3 v0.3.3+: Deep range narrative — if fromVersion considerably older than
|
|
1769
|
+
// the oldest available whatsnew, explicitly tell user this is a multi-version
|
|
1770
|
+
// upgrade where older changelog only lives on GitHub Release (not shipped).
|
|
1771
|
+
// Heuristic: deep range if fromVersion's major < oldest's major, or same major
|
|
1772
|
+
// but minor differs by ≥ 1 (i.e. fromVersion is at least one minor release older
|
|
1773
|
+
// than the oldest available whatsnew).
|
|
1774
|
+
const oldestAvailable = relevant[0];
|
|
1775
|
+
const [fromMajor, fromMinor] = fromVersion.split(".").map((n) => Number.parseInt(n, 10));
|
|
1776
|
+
const [oldMajor, oldMinor] = oldestAvailable.split(".").map((n) => Number.parseInt(n, 10));
|
|
1777
|
+
const isDeepRange = (fromMajor < oldMajor) || (fromMajor === oldMajor && fromMinor < oldMinor);
|
|
1778
|
+
if (isDeepRange) {
|
|
1779
|
+
console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion} 跨度較大;本工具 release notes 庫只 cover 由 v${oldestAvailable} 起嘅 ${relevant.length} 個版本。較舊版本(v${fromVersion} 至 v${oldestAvailable} 之前)嘅完整變更見:`);
|
|
1780
|
+
console.log(` https://github.com/Adamchanadam/agent-handoff-kit/releases`);
|
|
1781
|
+
console.log("");
|
|
1782
|
+
}
|
|
1783
|
+
|
|
1784
|
+
console.log(`📰 本次升級涵蓋 ${relevant.length} 個版本嘅 release notes(${isDeepRange ? `由 v${oldestAvailable} 起` : `v${fromVersion} → v${toVersion}`}):`);
|
|
1696
1785
|
console.log("");
|
|
1697
1786
|
|
|
1698
1787
|
const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# v0.3.3
|
|
2
|
+
|
|
3
|
+
## 本版新加咗咩
|
|
4
|
+
|
|
5
|
+
修補 v0.3.2 用戶實測揭發嘅兩個 narrative coherence bug。升級流程之後 doctor 唔再矛盾講「root 落後 CLI,建議 upgrade」——升完就對齊。跨多版本嘅升級(譬如 v0.1.x 直接升 v0.3.3),whatsnew summary 會明文話你跨度較大,並指你睇 GitHub Release 攞較舊版本嘅完整變更。
|
|
6
|
+
|
|
7
|
+
## 對你已有檔案嘅影響
|
|
8
|
+
|
|
9
|
+
完全冇影響 user content。Upgrade 之後 `dev/PROJECT_INDEX.md` 嘅「Agent Handoff Kit template version」一行會自動 update 為當前 CLI 版本(呢一行屬 template metadata,唔屬你填嘅內容);其他 row(譬如 External Sources、Fact Base、Workspace Identity)保持不變。
|
|
10
|
+
|
|
11
|
+
## 建議下一步
|
|
12
|
+
|
|
13
|
+
跑 doctor confirm 健康即可。
|
|
@@ -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,即代表這次熱修已生效。
|