@adamchanadam/agent-handoff-kit 0.3.1 → 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 +300 -6
- package/docs/whatsnew/v0.3.1.md +13 -0
- package/docs/whatsnew/v0.3.2.md +13 -0
- package/docs/whatsnew/v0.3.3.md +13 -0
- package/package.json +2 -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
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
import { createInterface } from "node:readline/promises";
|
|
4
4
|
import { stdin as input, stdout as output } from "node:process";
|
|
5
|
-
import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
|
|
5
|
+
import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
|
|
6
6
|
import path from "node:path";
|
|
7
7
|
import { fileURLToPath } from "node:url";
|
|
8
8
|
|
|
@@ -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,6 +515,31 @@ async function runInstall(command, root, options, version) {
|
|
|
498
515
|
created.push(item.targetRel);
|
|
499
516
|
}
|
|
500
517
|
|
|
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")) {
|
|
527
|
+
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
528
|
+
try {
|
|
529
|
+
const text = await readFile(indexPath, "utf8");
|
|
530
|
+
const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
|
|
531
|
+
if (m && isStableSemver(m[1]) && compareSemver(m[1], version) < 0) {
|
|
532
|
+
const updated = text.replace(
|
|
533
|
+
/\| Agent Handoff Kit template version \| [\d.]+ \|/,
|
|
534
|
+
`| Agent Handoff Kit template version | ${version} |`
|
|
535
|
+
);
|
|
536
|
+
await writeFile(indexPath, updated, "utf8");
|
|
537
|
+
}
|
|
538
|
+
} catch {
|
|
539
|
+
// ignore — doctor anchor (R-016) only checks row existence, not specific value.
|
|
540
|
+
}
|
|
541
|
+
}
|
|
542
|
+
|
|
501
543
|
for (const item of plan) {
|
|
502
544
|
if (item.action !== "merge") continue;
|
|
503
545
|
const backupPath = path.join(backupDir, item.targetRel);
|
|
@@ -532,11 +574,12 @@ async function runInstall(command, root, options, version) {
|
|
|
532
574
|
reportRel: path.relative(root, report)
|
|
533
575
|
});
|
|
534
576
|
|
|
535
|
-
// R-031 v0.3.1+: install vs upgrade narrative split.
|
|
536
|
-
//
|
|
537
|
-
//
|
|
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.
|
|
538
581
|
if (command === "upgrade") {
|
|
539
|
-
printUpgradeNextSteps(root, conflicts.length);
|
|
582
|
+
await printUpgradeNextSteps(root, conflicts.length, version, preUpgradeRootVersion);
|
|
540
583
|
} else {
|
|
541
584
|
printInstallNextSteps(root, conflicts.length);
|
|
542
585
|
}
|
|
@@ -661,6 +704,18 @@ async function runDoctor(root, version, options = {}) {
|
|
|
661
704
|
}
|
|
662
705
|
}
|
|
663
706
|
|
|
707
|
+
// R-031.2 v0.3.2+: 項目狀態速覽 —— 三向 version 對比 + 距上次 closeout 幾耐 +
|
|
708
|
+
// 項目首次安裝距今幾耐。從用戶跑 doctor 嗰刻嘅 mental state 出發(confirm health /
|
|
709
|
+
// suspect drift / curious about version / continuity awareness),唔等用戶 ask AI。
|
|
710
|
+
console.log("");
|
|
711
|
+
console.log("項目狀態速覽:");
|
|
712
|
+
const versionAlignment = await assessVersionAlignment(root, version);
|
|
713
|
+
printVersionAlignment(versionAlignment);
|
|
714
|
+
const lastCloseout = await assessLastCloseout(root);
|
|
715
|
+
printLastCloseout(lastCloseout);
|
|
716
|
+
const projectAge = await assessProjectAge(root);
|
|
717
|
+
printProjectAge(projectAge);
|
|
718
|
+
|
|
664
719
|
const overallHealthy = credentialResult.ok;
|
|
665
720
|
printDoctorSummary(version, root, overallHealthy ? "healthy" : "needs-attention", {
|
|
666
721
|
checked: rows.length + anchorRows.length + schemaRows.length + mirrorRows.length + 2,
|
|
@@ -989,6 +1044,137 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
989
1044
|
return { ...base, action: "skip", reason: "preserve existing file" };
|
|
990
1045
|
}
|
|
991
1046
|
|
|
1047
|
+
// R-031.2 v0.3.2+: Version alignment assessment for doctor "項目狀態速覽".
|
|
1048
|
+
// Compares CLI version (running), root template metadata version (in dev/PROJECT_INDEX.md),
|
|
1049
|
+
// and npm latest. Surfaces drift awareness because previous design relied on startup
|
|
1050
|
+
// maybePrintUpdateNotice which silently fails when npx auto-fetches latest (CLI version
|
|
1051
|
+
// equals npm latest, so the notice never triggers, leaving user root drift invisible).
|
|
1052
|
+
async function assessVersionAlignment(root, cliVersion) {
|
|
1053
|
+
const indexPath = path.join(root, "dev/PROJECT_INDEX.md");
|
|
1054
|
+
let rootVersion = null;
|
|
1055
|
+
try {
|
|
1056
|
+
const text = await readFile(indexPath, "utf8");
|
|
1057
|
+
const m = text.match(/\| Agent Handoff Kit template version \| ([\d.]+) \|/);
|
|
1058
|
+
if (m) rootVersion = m[1];
|
|
1059
|
+
} catch {
|
|
1060
|
+
// file missing or unreadable; rootVersion stays null
|
|
1061
|
+
}
|
|
1062
|
+
|
|
1063
|
+
let npmLatest = null;
|
|
1064
|
+
try {
|
|
1065
|
+
npmLatest = await fetchLatestVersion();
|
|
1066
|
+
} catch {
|
|
1067
|
+
// network failure; npmLatest stays null
|
|
1068
|
+
}
|
|
1069
|
+
|
|
1070
|
+
return { cliVersion, rootVersion, npmLatest };
|
|
1071
|
+
}
|
|
1072
|
+
|
|
1073
|
+
function printVersionAlignment(result) {
|
|
1074
|
+
const { cliVersion, rootVersion, npmLatest } = result;
|
|
1075
|
+
if (rootVersion === null) {
|
|
1076
|
+
console.log(` 📦 版本:CLI v${cliVersion} / root metadata 缺失(曾經手動編輯?)/ npm latest ${npmLatest ? "v" + npmLatest : "無法查詢"}`);
|
|
1077
|
+
return;
|
|
1078
|
+
}
|
|
1079
|
+
if (npmLatest === null) {
|
|
1080
|
+
console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest 無法查詢(網絡可能不通)`);
|
|
1081
|
+
return;
|
|
1082
|
+
}
|
|
1083
|
+
const aligned = cliVersion === rootVersion && rootVersion === npmLatest;
|
|
1084
|
+
if (aligned) {
|
|
1085
|
+
console.log(` 📦 版本:CLI / root / npm latest 三向對齊 v${cliVersion} ✅`);
|
|
1086
|
+
return;
|
|
1087
|
+
}
|
|
1088
|
+
console.log(` 📦 版本:CLI v${cliVersion} / root v${rootVersion} / npm latest v${npmLatest}`);
|
|
1089
|
+
if (npmLatest && compareSemver(npmLatest, cliVersion) > 0) {
|
|
1090
|
+
console.log(` npm 有新版(v${npmLatest});可執行:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
|
|
1091
|
+
} else if (cliVersion !== rootVersion) {
|
|
1092
|
+
console.log(` 你 root template metadata 同 CLI 唔對齊;兩個版本仍相容 doctor 仍 PASS;如想對齊:npx @adamchanadam/agent-handoff-kit@latest upgrade`);
|
|
1093
|
+
}
|
|
1094
|
+
}
|
|
1095
|
+
|
|
1096
|
+
// R-031.2 v0.3.2+: Last closeout assessment. Reads dev/SESSION_HANDOFF.md "Last Updated:"
|
|
1097
|
+
// line (strict format, reliable). Falls back to dev/SESSION_LOG.md first H2 date if
|
|
1098
|
+
// HANDOFF missing or unparseable.
|
|
1099
|
+
async function assessLastCloseout(root) {
|
|
1100
|
+
const handoffPath = path.join(root, "dev/SESSION_HANDOFF.md");
|
|
1101
|
+
let date = null;
|
|
1102
|
+
try {
|
|
1103
|
+
const text = await readFile(handoffPath, "utf8");
|
|
1104
|
+
const m = text.match(/Last Updated:\s*(\d{4}-\d{2}-\d{2})/);
|
|
1105
|
+
if (m) date = m[1];
|
|
1106
|
+
} catch {
|
|
1107
|
+
// ignore
|
|
1108
|
+
}
|
|
1109
|
+
|
|
1110
|
+
if (!date) {
|
|
1111
|
+
const logPath = path.join(root, "dev/SESSION_LOG.md");
|
|
1112
|
+
try {
|
|
1113
|
+
const text = await readFile(logPath, "utf8");
|
|
1114
|
+
const m = text.match(/^## (\d{4}-\d{2}-\d{2})/m);
|
|
1115
|
+
if (m) date = m[1];
|
|
1116
|
+
} catch {
|
|
1117
|
+
// ignore
|
|
1118
|
+
}
|
|
1119
|
+
}
|
|
1120
|
+
|
|
1121
|
+
return { date };
|
|
1122
|
+
}
|
|
1123
|
+
|
|
1124
|
+
function printLastCloseout(result) {
|
|
1125
|
+
if (!result.date) {
|
|
1126
|
+
console.log(" 📅 上次 closeout:(仲未 closeout 過。第一次完成 task 後可以講 AI「收工」)");
|
|
1127
|
+
return;
|
|
1128
|
+
}
|
|
1129
|
+
const today = new Date();
|
|
1130
|
+
const closeout = new Date(result.date);
|
|
1131
|
+
const daysDiff = Math.floor((today - closeout) / (1000 * 60 * 60 * 24));
|
|
1132
|
+
if (daysDiff < 0) {
|
|
1133
|
+
console.log(` 📅 上次 closeout:${result.date}(日期超前?檢查系統時鐘)`);
|
|
1134
|
+
} else if (daysDiff === 0) {
|
|
1135
|
+
console.log(` 📅 上次 closeout:今日(${result.date})`);
|
|
1136
|
+
} else if (daysDiff <= 30) {
|
|
1137
|
+
console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})`);
|
|
1138
|
+
} else {
|
|
1139
|
+
console.log(` 📅 上次 closeout:${daysDiff} 日前(${result.date})— 建議跑下 closeout 整理進度`);
|
|
1140
|
+
}
|
|
1141
|
+
}
|
|
1142
|
+
|
|
1143
|
+
// R-031.2 v0.3.2+: Project age assessment. Reads the oldest folder timestamp in
|
|
1144
|
+
// dev/governance_migrations/ which records the first install date. Read-only; doctor
|
|
1145
|
+
// remains side-effect-free (no new write logic).
|
|
1146
|
+
async function assessProjectAge(root) {
|
|
1147
|
+
const migrationsDir = path.join(root, "dev/governance_migrations");
|
|
1148
|
+
try {
|
|
1149
|
+
const entries = await readdir(migrationsDir);
|
|
1150
|
+
const timestamps = entries.filter((name) => /^\d{8}T\d{6}Z$/.test(name)).sort();
|
|
1151
|
+
if (timestamps.length === 0) return { firstInstall: null };
|
|
1152
|
+
const oldest = timestamps[0];
|
|
1153
|
+
// Format: 20260423T112233Z → 2026-04-23
|
|
1154
|
+
const year = oldest.slice(0, 4);
|
|
1155
|
+
const month = oldest.slice(4, 6);
|
|
1156
|
+
const day = oldest.slice(6, 8);
|
|
1157
|
+
return { firstInstall: `${year}-${month}-${day}` };
|
|
1158
|
+
} catch {
|
|
1159
|
+
return { firstInstall: null };
|
|
1160
|
+
}
|
|
1161
|
+
}
|
|
1162
|
+
|
|
1163
|
+
function printProjectAge(result) {
|
|
1164
|
+
if (!result.firstInstall) {
|
|
1165
|
+
console.log(" 🌱 項目首次安裝距今:未知(dev/governance_migrations/ 未有 timestamp)");
|
|
1166
|
+
return;
|
|
1167
|
+
}
|
|
1168
|
+
const today = new Date();
|
|
1169
|
+
const firstInstall = new Date(result.firstInstall);
|
|
1170
|
+
const daysDiff = Math.floor((today - firstInstall) / (1000 * 60 * 60 * 24));
|
|
1171
|
+
if (daysDiff === 0) {
|
|
1172
|
+
console.log(` 🌱 項目首次安裝距今:今日(${result.firstInstall})`);
|
|
1173
|
+
} else {
|
|
1174
|
+
console.log(` 🌱 項目首次安裝距今:${daysDiff} 日(自 ${result.firstInstall})`);
|
|
1175
|
+
}
|
|
1176
|
+
}
|
|
1177
|
+
|
|
992
1178
|
// R-010 SESSION_LOG handoff-role discipline (warn-only doctor check).
|
|
993
1179
|
// Returns { ok, warnings } where:
|
|
994
1180
|
// - ok: true if no warnings triggered
|
|
@@ -1423,6 +1609,19 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1423
1609
|
console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
|
|
1424
1610
|
console.log("");
|
|
1425
1611
|
}
|
|
1612
|
+
// R-031.2 v0.3.2+: 「點 confirm 你裝啱咗」mini-checklist,直接答用戶第一次安裝後嘅
|
|
1613
|
+
// anxiety「我裝啱咗嗎」。三個具體 verify step + 一句講清本工具係 background harness
|
|
1614
|
+
// (冇 GUI、冇 server、需要連住 AI tool 先見到實際 value)。
|
|
1615
|
+
console.log("📋 點 confirm 你裝啱咗:");
|
|
1616
|
+
console.log("");
|
|
1617
|
+
console.log(" 1. 跑 npx @adamchanadam/agent-handoff-kit doctor 應該見到「status: passed」");
|
|
1618
|
+
console.log(" 2. 你 dev/ folder 應該有起碼 14 個檔(rules / SESSION_HANDOFF / SESSION_LOG 等)");
|
|
1619
|
+
console.log(" 3. 喺你 AI tool(Claude Code / Codex / Gemini)開新對話,貼下面起步句先見到實際 value");
|
|
1620
|
+
console.log("");
|
|
1621
|
+
console.log("⚠️ 注意:Agent Handoff Kit 只係 background harness —— 喺你 project folder 入面嘅幾類檔案。");
|
|
1622
|
+
console.log(" 冇 GUI、唔 run server、唔自動做嘢。你需要連住至少一個 AI tool 嘅對話,AI 先會讀依啲檔案做正事。");
|
|
1623
|
+
console.log("");
|
|
1624
|
+
console.log("------------------------------------------------------------");
|
|
1426
1625
|
console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
|
|
1427
1626
|
console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
|
|
1428
1627
|
console.log("------------------------------------------------------------");
|
|
@@ -1443,7 +1642,7 @@ function printInstallNextSteps(root, conflictCount) {
|
|
|
1443
1642
|
// R-031 v0.3.1+: Upgrade substantive next-step block. Distinct from install
|
|
1444
1643
|
// (`printInstallNextSteps`) because the user is not first-time; pushing them through
|
|
1445
1644
|
// the onboarding canonical phrase resets context they already have.
|
|
1446
|
-
function printUpgradeNextSteps(root, conflictCount) {
|
|
1645
|
+
async function printUpgradeNextSteps(root, conflictCount, version, preUpgradeRootVersion) {
|
|
1447
1646
|
console.log("");
|
|
1448
1647
|
console.log("============================================================");
|
|
1449
1648
|
console.log("✅ 升級完成:管治架構檔案已更新到最新版本");
|
|
@@ -1454,6 +1653,12 @@ function printUpgradeNextSteps(root, conflictCount) {
|
|
|
1454
1653
|
console.log("📋 下一步:把 migration report 或這段輸出貼給 AI,請它幫你判斷怎樣合併。");
|
|
1455
1654
|
console.log("");
|
|
1456
1655
|
}
|
|
1656
|
+
// R-031.2 v0.3.2+: Inline whatsnew summary — directly surface what changed in this
|
|
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);
|
|
1457
1662
|
console.log("📋 如你正在進行中的工作 session 已熟悉 Agent Handoff Kit,繼續使用原本的開工方式即可,無需重新做新手引導。");
|
|
1458
1663
|
console.log("");
|
|
1459
1664
|
console.log("💡 如想了解本版本新加了甚麼功能,可選用以下開工句(非強制):");
|
|
@@ -1465,6 +1670,95 @@ function printUpgradeNextSteps(root, conflictCount) {
|
|
|
1465
1670
|
console.log("============================================================");
|
|
1466
1671
|
}
|
|
1467
1672
|
|
|
1673
|
+
// R-031.2 v0.3.2+: Print whatsnew summaries for the version range crossed by this
|
|
1674
|
+
// upgrade. fromVersion = user root template metadata version (the state before
|
|
1675
|
+
// upgrade; R-016 preserves this row so it still reflects the prior state after
|
|
1676
|
+
// upgrade finishes). toVersion = current CLI version. Range is exclusive-fromVersion
|
|
1677
|
+
// inclusive-toVersion. Limit to first + last when crossing > 3 versions (elide middle).
|
|
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
|
+
}
|
|
1692
|
+
}
|
|
1693
|
+
if (!fromVersion || !isStableSemver(fromVersion) || compareSemver(fromVersion, toVersion) >= 0) {
|
|
1694
|
+
return;
|
|
1695
|
+
}
|
|
1696
|
+
|
|
1697
|
+
const whatsnewDir = path.join(packageRoot, "docs/whatsnew");
|
|
1698
|
+
let entries = [];
|
|
1699
|
+
try {
|
|
1700
|
+
entries = await readdir(whatsnewDir);
|
|
1701
|
+
} catch {
|
|
1702
|
+
console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${toVersion}`);
|
|
1703
|
+
console.log("");
|
|
1704
|
+
return;
|
|
1705
|
+
}
|
|
1706
|
+
|
|
1707
|
+
const relevant = entries
|
|
1708
|
+
.filter((name) => /^v\d+\.\d+\.\d+\.md$/.test(name))
|
|
1709
|
+
.map((name) => name.replace(/^v/, "").replace(/\.md$/, ""))
|
|
1710
|
+
.filter((v) => compareSemver(v, fromVersion) > 0 && compareSemver(v, toVersion) <= 0)
|
|
1711
|
+
.sort((a, b) => compareSemver(a, b));
|
|
1712
|
+
|
|
1713
|
+
if (relevant.length === 0) {
|
|
1714
|
+
console.log(`💡 本版 release notes:https://github.com/Adamchanadam/agent-handoff-kit/releases`);
|
|
1715
|
+
console.log(` (v${fromVersion} → v${toVersion} 跨版本嘅完整變更見 GitHub Release 全列表)`);
|
|
1716
|
+
console.log("");
|
|
1717
|
+
return;
|
|
1718
|
+
}
|
|
1719
|
+
|
|
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}`}):`);
|
|
1737
|
+
console.log("");
|
|
1738
|
+
|
|
1739
|
+
const toShow = relevant.length <= 3 ? relevant : [relevant[0], relevant[relevant.length - 1]];
|
|
1740
|
+
const elidedCount = relevant.length > 3 ? relevant.length - 2 : 0;
|
|
1741
|
+
|
|
1742
|
+
for (let i = 0; i < toShow.length; i += 1) {
|
|
1743
|
+
const v = toShow[i];
|
|
1744
|
+
const filePath = path.join(whatsnewDir, `v${v}.md`);
|
|
1745
|
+
try {
|
|
1746
|
+
const content = await readFile(filePath, "utf8");
|
|
1747
|
+
console.log(content.trimEnd());
|
|
1748
|
+
console.log("");
|
|
1749
|
+
if (i === 0 && elidedCount > 0) {
|
|
1750
|
+
console.log(` ⋯ 中間 ${elidedCount} 個版本嘅 release notes 略;完整列表見 https://github.com/Adamchanadam/agent-handoff-kit/releases ⋯`);
|
|
1751
|
+
console.log("");
|
|
1752
|
+
}
|
|
1753
|
+
} catch {
|
|
1754
|
+
console.log(`(v${v} release notes 檔缺失,見 https://github.com/Adamchanadam/agent-handoff-kit/releases/tag/v${v})`);
|
|
1755
|
+
console.log("");
|
|
1756
|
+
}
|
|
1757
|
+
}
|
|
1758
|
+
console.log("------------------------------------------------------------");
|
|
1759
|
+
console.log("");
|
|
1760
|
+
}
|
|
1761
|
+
|
|
1468
1762
|
// R-031 v0.3.1+: Upgrade no-op short-circuit. When the user runs upgrade on a root
|
|
1469
1763
|
// already at latest version (skip all / create 0 / merge 0 / conflict 0), print a
|
|
1470
1764
|
// short factual message and return. Saves disk (no migration report) + reduces noise
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# v0.3.1
|
|
2
|
+
|
|
3
|
+
## 本版新加咗咩
|
|
4
|
+
|
|
5
|
+
CLI 升級流程嘅 messaging 改進 —— 你升完或者第二次跑 upgrade 嗰陣會見到唔同 output。第二次跑 upgrade(零改動)會直接短訊「你已係最新版本」,唔再印「安裝完成」+ 新手起步句嘅完整 ceremony。
|
|
6
|
+
|
|
7
|
+
## 對你已有檔案嘅影響
|
|
8
|
+
|
|
9
|
+
完全冇影響。純 CLI source 改進,無 user-facing template 改動,doctor 對既有用戶仍 PASS。
|
|
10
|
+
|
|
11
|
+
## 建議下一步
|
|
12
|
+
|
|
13
|
+
跑 doctor confirm 健康即可。
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# v0.3.2
|
|
2
|
+
|
|
3
|
+
## 本版新加咗咩
|
|
4
|
+
|
|
5
|
+
Doctor 同 init 命令加入「項目狀態速覽」+「點 confirm 你裝啱咗」。Doctor 跑完會印你嘅版本對齊狀況(CLI / root template / npm latest 三向比較)、上次 closeout 距今幾耐、項目首次安裝距今幾耐。Init 完會印 mini-checklist 答「我裝啱咗嗎」嘅 anxiety,並講清本工具係 background harness(需要連住 AI tool 先見到實際 value)。Upgrade 完會直接 inline print 本版同跨版本嘅 whatsnew 摘要(即你而家睇緊呢段),唔等你 ask AI。
|
|
6
|
+
|
|
7
|
+
## 對你已有檔案嘅影響
|
|
8
|
+
|
|
9
|
+
完全冇影響。純 CLI source 改進,無 user-facing template 改動,doctor 對既有用戶仍 PASS。
|
|
10
|
+
|
|
11
|
+
## 建議下一步
|
|
12
|
+
|
|
13
|
+
跑 doctor confirm 健康,順便試吓本版新加嘅「項目狀態速覽」。
|
|
@@ -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 健康即可。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.3",
|
|
4
4
|
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
"bin/",
|
|
11
11
|
"runtime-core/",
|
|
12
12
|
"packs/",
|
|
13
|
+
"docs/whatsnew/",
|
|
13
14
|
"README.md",
|
|
14
15
|
"LICENSE"
|
|
15
16
|
],
|