@adamchanadam/agent-handoff-kit 0.1.2 → 0.1.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 CHANGED
@@ -1,6 +1,6 @@
1
1
  # Agent Handoff Kit
2
2
 
3
- 狀態:`v0.1.2` 已正式發佈。這是早期可用版本,尚未宣稱所有需求已完成。
3
+ 狀態:`v0.1.3` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
4
4
 
5
5
  Agent Handoff Kit 是一套給 AI 專案使用的交接工具。它會在你的專案中放入一組固定文件,讓 AI 在下一次工作時知道:目前做到哪裡、哪些資料要先讀、哪些檔案不可亂動、收工時要留下甚麼。
6
6
 
@@ -65,8 +65,7 @@ yes
65
65
  你可以貼上類似以下文字:
66
66
 
67
67
  ```text
68
- Work in <你的專案資料夾>.
69
- Read AGENTS.md first. Tell me what you understand before changing files.
68
+ Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
70
69
  ```
71
70
 
72
71
  接著再寫你的任務,例如:
@@ -93,6 +92,16 @@ npx @adamchanadam/agent-handoff-kit doctor
93
92
 
94
93
  這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
95
94
 
95
+ ## 版本提示
96
+
97
+ CLI 執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
98
+
99
+ 若你不想檢查更新,可設定:
100
+
101
+ ```bash
102
+ AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
103
+ ```
104
+
96
105
  ## 會安裝甚麼
97
106
 
98
107
  安裝工具會在你的專案中建立以下文件:
@@ -127,14 +136,19 @@ dev/rules/*.md
127
136
 
128
137
  ## 日常使用方式
129
138
 
130
- 每次開始新的 AI 工作階段時,建議先貼上上一輪收工產生的開工文字。若沒有那段文字,可以貼:
139
+ 每次開始新的 AI 工作階段,有兩種做法:
140
+
141
+ 1. 最佳:貼上上一輪收工產生的開工文字。那段文字內容最完整、最準確。
142
+ 2. 沒有那段文字時,貼上這一句就夠:
131
143
 
132
144
  ```text
133
- Work in <你的專案資料夾>.
134
- Read AGENTS.md, dev/SESSION_HANDOFF.md, dev/SESSION_LOG.md, dev/PROJECT_INDEX.md, and dev/RULE_PACKS.md.
135
- Tell me the current objective, pending work, risks, and your recommended next action before changing files.
145
+ Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
136
146
  ```
137
147
 
148
+ 你不需要在提示內逐一列出檔案。`AGENTS.md` 本身已包含開工讀序,AI 讀它就會自行讀入交接、紀錄與索引。
149
+
150
+ 備用(只在你的 AI 工具沒有依 `AGENTS.md` 讀時才需要):在上面那句後面加一句 `Also read dev/SESSION_HANDOFF.md and dev/SESSION_LOG.md.`。
151
+
138
152
  然後直接描述任務。
139
153
 
140
154
  對簡單任務,可以這樣寫:
@@ -228,8 +242,8 @@ npm package 只包含安裝所需內容:
228
242
 
229
243
  ## 目前限制
230
244
 
231
- - `v0.1.2` 是早期可用版本,尚未宣稱完整穩定。
232
- - 這仍是早期可用版本,尚未宣稱完整穩定。
245
+ - `v0.1.3` 是 GitHub 與 npm 同步發佈版本。
246
+ - 這是早期可用版本,尚未宣稱完整穩定。
233
247
  - 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
234
248
  - `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
235
249
  - 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
@@ -132,8 +132,7 @@ const requiredAnchors = [
132
132
  target: "dev/PROJECT_INDEX.md",
133
133
  label: "template version metadata",
134
134
  snippets: [
135
- "Agent Handoff Kit template version",
136
- "0.1.2"
135
+ "Agent Handoff Kit template version"
137
136
  ]
138
137
  },
139
138
  {
@@ -259,6 +258,7 @@ main().catch((error) => {
259
258
 
260
259
  async function main() {
261
260
  const version = await readPackageVersion();
261
+ await maybePrintUpdateNotice(version);
262
262
  const { command, options } = parseArgs(process.argv.slice(2));
263
263
  if (!command || options.help) {
264
264
  printHelp(version);
@@ -343,12 +343,12 @@ async function runInstall(command, root, options, version) {
343
343
  }
344
344
 
345
345
  const report = await writeMigrationReport(root, command, mode, plan, created, merged, conflicts, migrationDir, backupDir);
346
- console.log(`\ncreated: ${created.length}`);
347
- console.log(`merged: ${merged.length}`);
348
- console.log(`skipped existing: ${plan.filter((item) => item.action === "skip").length}`);
349
- console.log(`conflict: ${conflicts.length}`);
350
- if (merged.length > 0) console.log(`backup: ${path.relative(root, backupDir)}`);
351
- console.log(`migration report: ${path.relative(root, report)}`);
346
+ console.log(`\n✅ created: ${created.length}`);
347
+ console.log(`🔀 merged: ${merged.length}`);
348
+ console.log(`⏭️ skipped existing: ${plan.filter((item) => item.action === "skip").length}`);
349
+ console.log(`${conflicts.length > 0 ? "⚠️ " : "✅ "}conflict: ${conflicts.length}`);
350
+ if (merged.length > 0) console.log(`💾 backup: ${path.relative(root, backupDir)}`);
351
+ console.log(`📄 migration report: ${path.relative(root, report)}`);
352
352
  printInstallNextSteps(root, conflicts.length);
353
353
  if (conflicts.length > 0) process.exitCode = 1;
354
354
  }
@@ -632,6 +632,89 @@ async function readPackageVersion() {
632
632
  }
633
633
  }
634
634
 
635
+ async function maybePrintUpdateNotice(currentVersion) {
636
+ if (shouldSkipUpdateCheck()) return;
637
+ if (!isStableSemver(currentVersion)) return;
638
+
639
+ const latestVersion = await fetchLatestVersion();
640
+ if (!latestVersion || !isStableSemver(latestVersion)) return;
641
+ if (compareSemver(latestVersion, currentVersion) <= 0) return;
642
+
643
+ printUpdateNotice(currentVersion, latestVersion);
644
+ }
645
+
646
+ function shouldSkipUpdateCheck() {
647
+ if (process.env.AGENT_HANDOFF_KIT_NO_UPDATE_CHECK === "1") return true;
648
+ if (process.env.AGENT_HANDOFF_KIT_UPDATE_CHECK_FORCE === "1") return false;
649
+ if (process.env.CI) return true;
650
+ if ((process.env.npm_lifecycle_event ?? "").startsWith("qa:")) return true;
651
+ return false;
652
+ }
653
+
654
+ async function fetchLatestVersion() {
655
+ if (process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST) {
656
+ return process.env.AGENT_HANDOFF_KIT_UPDATE_MOCK_LATEST;
657
+ }
658
+ const url = process.env.AGENT_HANDOFF_KIT_UPDATE_REGISTRY_URL
659
+ ?? "https://registry.npmjs.org/@adamchanadam%2Fagent-handoff-kit/latest";
660
+ const timeoutMs = Number.parseInt(process.env.AGENT_HANDOFF_KIT_UPDATE_TIMEOUT_MS ?? "1200", 10);
661
+ const controller = new AbortController();
662
+ const timer = setTimeout(() => controller.abort(), Number.isFinite(timeoutMs) ? timeoutMs : 1200);
663
+ try {
664
+ const response = await fetch(url, {
665
+ headers: { accept: "application/vnd.npm.install-v1+json, application/json" },
666
+ signal: controller.signal
667
+ });
668
+ if (!response.ok) return null;
669
+ const data = await response.json();
670
+ return typeof data.version === "string" ? data.version : null;
671
+ } catch {
672
+ return null;
673
+ } finally {
674
+ clearTimeout(timer);
675
+ }
676
+ }
677
+
678
+ function isStableSemver(version) {
679
+ return /^\d+\.\d+\.\d+$/.test(version);
680
+ }
681
+
682
+ function compareSemver(left, right) {
683
+ const leftParts = left.split(".").map((part) => Number.parseInt(part, 10));
684
+ const rightParts = right.split(".").map((part) => Number.parseInt(part, 10));
685
+ for (let i = 0; i < 3; i += 1) {
686
+ if (leftParts[i] > rightParts[i]) return 1;
687
+ if (leftParts[i] < rightParts[i]) return -1;
688
+ }
689
+ return 0;
690
+ }
691
+
692
+ function printUpdateNotice(currentVersion, latestVersion) {
693
+ const releaseUrl = "https://github.com/Adamchanadam/agent-handoff-kit/releases/latest";
694
+ const command = "npx @adamchanadam/agent-handoff-kit@latest <command>";
695
+ const lines = [
696
+ `✨ Update available! ${currentVersion} -> ${latestVersion}`,
697
+ `Run ${command} to use the latest version.`,
698
+ "",
699
+ "For global installs:",
700
+ "npm install -g @adamchanadam/agent-handoff-kit",
701
+ "",
702
+ "See full release notes:",
703
+ releaseUrl
704
+ ];
705
+ const width = Math.max(...lines.map((line) => visibleLength(line))) + 2;
706
+ console.log(`╭${"─".repeat(width)}╮`);
707
+ for (const line of lines) {
708
+ console.log(`│ ${line}${" ".repeat(width - visibleLength(line) - 1)}│`);
709
+ }
710
+ console.log(`╰${"─".repeat(width)}╯`);
711
+ console.log("");
712
+ }
713
+
714
+ function visibleLength(text) {
715
+ return [...text].length;
716
+ }
717
+
635
718
  function printCard(version, status, eyes) {
636
719
  console.log(` /\\_/\\ Agent Handoff Kit v${version}`);
637
720
  console.log(` ( ${eyes} ) ${status}`);
@@ -642,25 +725,24 @@ function printCard(version, status, eyes) {
642
725
  function printInstallNextSteps(root, conflictCount) {
643
726
  console.log("");
644
727
  console.log("============================================================");
645
- console.log("安裝完成:下一步請在 AI 對話中操作");
728
+ console.log("✅ 安裝完成:下一步請在 AI 對話中操作");
646
729
  console.log("============================================================");
647
730
  if (conflictCount > 0) {
648
- console.log("狀態:有檔案需要你先處理,詳情見 migration report。");
649
- console.log("請不要忽略 conflict,也不要直接覆寫既有檔案。");
731
+ console.log("⚠️ 狀態:有檔案需要你先處理,詳情見 migration report。");
732
+ console.log("⚠️ 請不要忽略 conflict,也不要直接覆寫既有檔案。");
650
733
  console.log("");
651
734
  }
652
- console.log("請注意:下面文字不是 Terminal 指令。");
653
- console.log("請打開你要使用的 AI 工具,新增一段對話,貼上:");
735
+ console.log("⚠️ 請注意:下面文字不是 Terminal 指令。");
736
+ console.log("📋 請打開你要使用的 AI 工具,新增一段對話,貼上下面一句:");
654
737
  console.log("------------------------------------------------------------");
655
- console.log(`Work in ${root}.`);
656
- console.log("Read AGENTS.md first. Tell me what you understand before changing files.");
738
+ console.log(`Work in ${root}. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.`);
657
739
  console.log("------------------------------------------------------------");
658
740
  console.log("");
659
- console.log("然後直接描述你的任務,例如:");
660
- console.log("整理這個專案,先告訴我你讀到的目前狀態與下一步。");
741
+ console.log("🚀 然後直接描述你的任務,例如:");
742
+ console.log(" 整理這個專案,先告訴我你讀到的目前狀態與下一步。");
661
743
  console.log("");
662
- console.log("如要檢查安裝是否完整,可在 Terminal 執行:");
663
- console.log("npx @adamchanadam/agent-handoff-kit doctor");
744
+ console.log("🩺 如要檢查安裝是否完整,可在 Terminal 執行:");
745
+ console.log(" npx @adamchanadam/agent-handoff-kit doctor");
664
746
  console.log("============================================================");
665
747
  }
666
748
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
6
6
 
7
7
  | Field | Value | Last verified |
8
8
  |---|---|---|
9
- | Agent Handoff Kit template version | 0.1.2 | package prototype |
9
+ | Agent Handoff Kit template version | 0.1.3 | package prototype |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |