@adamchanadam/agent-handoff-kit 0.3.2 → 0.3.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/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +69 -28
- package/docs/whatsnew/v0.3.3.md +13 -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.3` 已正式發佈到 GitHub 與 npm。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -467,6 +467,23 @@ async function runInstall(command, root, options, version) {
|
|
|
467
467
|
return;
|
|
468
468
|
}
|
|
469
469
|
|
|
470
|
+
// R-031.3 v0.3.3+: For upgrade scenarios, capture pre-upgrade root template version
|
|
471
|
+
// before the create/merge/inject loops mutate PROJECT_INDEX. This snapshot is later
|
|
472
|
+
// passed to printWhatsnew so the version range narrative reflects the actual user
|
|
473
|
+
// journey (v{pre-upgrade} → v{current CLI}), not the post-inject state which would
|
|
474
|
+
// make printWhatsnew see fromVersion == toVersion and skip the summary entirely.
|
|
475
|
+
let preUpgradeRootVersion = null;
|
|
476
|
+
if (command === "upgrade") {
|
|
477
|
+
try {
|
|
478
|
+
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
479
|
+
const text = await readFile(indexPath, "utf8");
|
|
480
|
+
const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
|
|
481
|
+
if (m) preUpgradeRootVersion = m[1];
|
|
482
|
+
} catch {
|
|
483
|
+
// ignore
|
|
484
|
+
}
|
|
485
|
+
}
|
|
486
|
+
|
|
470
487
|
printPlan(command, root, mode, plan, version);
|
|
471
488
|
|
|
472
489
|
if (options.dryRun) {
|
|
@@ -498,12 +515,15 @@ async function runInstall(command, root, options, version) {
|
|
|
498
515
|
created.push(item.targetRel);
|
|
499
516
|
}
|
|
500
517
|
|
|
501
|
-
// R-031.
|
|
502
|
-
//
|
|
503
|
-
//
|
|
504
|
-
//
|
|
505
|
-
//
|
|
506
|
-
|
|
518
|
+
// R-031.3 v0.3.3+: Inject current CLI version into PROJECT_INDEX template version
|
|
519
|
+
// metadata row — triggers for both fresh install AND upgrade substantive scenarios.
|
|
520
|
+
// The metadata row tracks template structure version (maintainer-owned), distinct
|
|
521
|
+
// from user content rows (External Sources / Fact Base etc.) which R-016 protects.
|
|
522
|
+
// Without inject on upgrade, user just upgraded but doctor's "項目狀態速覽"
|
|
523
|
+
// immediately prints "root 落後 CLI" — contradicting the just-completed upgrade
|
|
524
|
+
// narrative. Compare-semver guard prevents downgrade overwrite (e.g. someone
|
|
525
|
+
// running an older CLI). User content rows are preserved untouched.
|
|
526
|
+
if (command === "upgrade" || created.includes("dev/PROJECT_INDEX.md")) {
|
|
507
527
|
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
508
528
|
try {
|
|
509
529
|
const text = await readFile(indexPath, "utf8");
|
|
@@ -516,8 +536,7 @@ async function runInstall(command, root, options, version) {
|
|
|
516
536
|
await writeFile(indexPath, updated, "utf8");
|
|
517
537
|
}
|
|
518
538
|
} catch {
|
|
519
|
-
// ignore —
|
|
520
|
-
// checks for the row's existence, not a specific version.
|
|
539
|
+
// ignore — doctor anchor (R-016) only checks row existence, not specific value.
|
|
521
540
|
}
|
|
522
541
|
}
|
|
523
542
|
|
|
@@ -555,12 +574,12 @@ async function runInstall(command, root, options, version) {
|
|
|
555
574
|
reportRel: path.relative(root, report)
|
|
556
575
|
});
|
|
557
576
|
|
|
558
|
-
// R-031 v0.3.1+: install vs upgrade narrative split.
|
|
559
|
-
//
|
|
560
|
-
//
|
|
561
|
-
//
|
|
577
|
+
// R-031 v0.3.1+: install vs upgrade narrative split.
|
|
578
|
+
// R-031.2 v0.3.2+: printUpgradeNextSteps async (awaits inline whatsnew print).
|
|
579
|
+
// R-031.3 v0.3.3+: pass preUpgradeRootVersion so whatsnew narrative reflects the
|
|
580
|
+
// actual user journey (v{pre-upgrade} → v{current}), not the post-inject state.
|
|
562
581
|
if (command === "upgrade") {
|
|
563
|
-
await printUpgradeNextSteps(root, conflicts.length, version);
|
|
582
|
+
await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
|
|
564
583
|
} else {
|
|
565
584
|
printInstallNextSteps(root, conflicts.length);
|
|
566
585
|
}
|
|
@@ -1623,7 +1642,7 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1623
1642
|
// R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
|
|
1624
1643
|
// (`printInstallNextSteps`) because the user is not first-time; pushing them through
|
|
1625
1644
|
// the onboarding canonical phrase resets context they already have.
|
|
1626
|
-
async function printUpgradeNextSteps(root, conflictCount, version) {
|
|
1645
|
+
async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
|
|
1627
1646
|
console.log("");
|
|
1628
1647
|
console.log("============================================================");
|
|
1629
1648
|
console.log("✅ 升級完成:管治架構檔案已更新到最新版本");
|
|
@@ -1635,10 +1654,11 @@ async function printUpgradeNextSteps(root, conflictCount, version) {
|
|
|
1635
1654
|
console.log("");
|
|
1636
1655
|
}
|
|
1637
1656
|
// 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
|
-
|
|
1657
|
+
// version (and any intermediate versions the user skipped).
|
|
1658
|
+
// R-031.3 v0.3.3+: fromVersion now uses pre-upgrade snapshot (captured before
|
|
1659
|
+
// inject mutated PROJECT_INDEX), so the range narrative reflects actual user
|
|
1660
|
+
// journey instead of degenerate v{current} → v{current}.
|
|
1661
|
+
await printWhatsnew(root, version, preUpgradeRootVersion);
|
|
1642
1662
|
console.log("📋 如你正在進行中的工作 session 已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
|
|
1643
1663
|
console.log("");
|
|
1644
1664
|
console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
|
|
@@ -1655,15 +1675,20 @@ async function printUpgradeNextSteps(root, conflictCount, version) {
|
|
|
1655
1675
|
// upgrade; R-016 preserves this row so it still reflects the prior state after
|
|
1656
1676
|
// upgrade finishes). toVersion = current CLI version. Range is exclusive-fromVersion
|
|
1657
1677
|
// 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
|
-
|
|
1678
|
+
async function printWhatsnew(root, toVersion, fromVersionOverride) {
|
|
1679
|
+
// R-031.3 v0.3.3+: fromVersion sourced from explicit override (pre-upgrade snapshot)
|
|
1680
|
+
// when called from upgrade flow; falls back to reading current PROJECT_INDEX
|
|
1681
|
+
// template version row otherwise.
|
|
1682
|
+
let fromVersion = fromVersionOverride ?? null;
|
|
1683
|
+
if (!fromVersion) {
|
|
1684
|
+
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
1685
|
+
try {
|
|
1686
|
+
const text = await readFile(indexPath, "utf8");
|
|
1687
|
+
const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
|
|
1688
|
+
if (m) fromVersion = m[1];
|
|
1689
|
+
} catch {
|
|
1690
|
+
return;
|
|
1691
|
+
}
|
|
1667
1692
|
}
|
|
1668
1693
|
if (!fromVersion || !isStableSemver(fromVersion) || compareSemver(fromVersion, toVersion) >= 0) {
|
|
1669
1694
|
return;
|
|
@@ -1692,7 +1717,23 @@ async function printWhatsnew(root, toVersion) {
|
|
|
1692
1717
|
return;
|
|
1693
1718
|
}
|
|
1694
1719
|
|
|
1695
|
-
|
|
1720
|
+
// R-031.3 v0.3.3+: Deep range narrative — if fromVersion considerably older than
|
|
1721
|
+
// the oldest available whatsnew, explicitly tell user this is a multi-version
|
|
1722
|
+
// upgrade where older changelog only lives on GitHub Release (not shipped).
|
|
1723
|
+
// Heuristic: deep range if fromVersion's major < oldest's major, or same major
|
|
1724
|
+
// but minor differs by ≥ 1 (i.e. fromVersion is at least one minor release older
|
|
1725
|
+
// than the oldest available whatsnew).
|
|
1726
|
+
const oldestAvailable = relevant[0];
|
|
1727
|
+
const [fromMajor, fromMinor] = fromVersion.split(".").map((n) => Number.parseInt(n, 10));
|
|
1728
|
+
const [oldMajor, oldMinor] = oldestAvailable.split(".").map((n) => Number.parseInt(n, 10));
|
|
1729
|
+
const isDeepRange = (fromMajor < oldMajor) || (fromMajor === oldMajor && fromMinor < oldMinor);
|
|
1730
|
+
if (isDeepRange) {
|
|
1731
|
+
console.log(`💡 注意:本次升級 v${fromVersion} → v${toVersion} 跨度較大;本工具 release notes 庫只 cover 由 v${oldestAvailable} 起嘅 ${relevant.length} 個版本。較舊版本(v${fromVersion} 至 v${oldestAvailable} 之前)嘅完整變更見:`);
|
|
1732
|
+
console.log(` https://github.com/Adamchanadam/agent-handoff-kit/releases`);
|
|
1733
|
+
console.log("");
|
|
1734
|
+
}
|
|
1735
|
+
|
|
1736
|
+
console.log(`📰 本次升級涵蓋 ${relevant.length} 個版本嘅 release notes(${isDeepRange ? `由 v${oldestAvailable} 起` : `v${fromVersion} → v${toVersion}`}):`);
|
|
1696
1737
|
console.log("");
|
|
1697
1738
|
|
|
1698
1739
|
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 健康即可。
|